Aspose::Words::Fields::Field Class Reference

Represents a Microsoft Word document field.

A field in a Word document is a complex structure consisting of multiple nodes that include field start, field code, field separator, field result and field end. Fields can be nested, contain rich content and span multiple paragraphs or sections in a document. The Field class is a "facade" object that provides properties and methods that allow to work with a field as a single object.

The Start, Separator and End properties point to the field start, separator and end nodes of the field respectively.

The content between the field start and separator is the field code. The content between the field separator and field end is the field result. The field code typically consists of one or more Run objects that specify instructions. The processing application is expected to execute the field code to calculate the field result.

The process of calculating field results is called the field update. Aspose.Words can update field results of most of the field types in exactly the same way as Microsoft Word does it. Most notably, Aspose.Words can calculate results of even the most complex formula fields. To calculate the field result of a single field use the Update method. To update fields in the whole document use UpdateFields.

You can get the plain text version of the field code using the GetFieldCode() method. You can get and set the plain text version of the field result using the Result property. Both the field code and field result can contain complex content, such as nested fields, paragraphs, shapes, tables and in this case you might want to work with the field nodes directly if you need more control.

You do not create instances of the Field class directly. To create a new field use the InsertField() method.

Examples

Shows how to insert a field into a document using a field code.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
 
SharedPtr<Field> field = builder->InsertField(u"DATE \\@ \"dddd, MMMM dd, yyyy\"");
 
ASSERT_EQ(FieldType::FieldDate, field->get_Type());
ASSERT_EQ(u"DATE \\@ \"dddd, MMMM dd, yyyy\"", field->GetFieldCode());
 
// This overload of the InsertField method automatically updates inserted fields.
ASSERT_LE(System::Math::Abs((System::DateTime::Parse(field->get_Result()) - System::DateTime::get_Today()).get_Hours()), 24);

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

Inheritance diagram for Aspose::Words::Fields::Field:

Public Member Functions
String	get_DisplayResult ()
	Gets the text that represents the displayed field result. More...
SharedPtr< FieldEnd >	get_End () const
	Gets the node that represents the field end. More...
SharedPtr< FieldEnd >	get_FieldEnd () const
	Gets the node that represents the field end. More...
SharedPtr< FieldStart >	get_FieldStart () const
	Gets the node that represents the start of the field. More...
SharedPtr< FieldFormat >	get_Format ()
	Gets a FieldFormat object that provides typed access to field's formatting. More...
bool	get_IsDirty ()
	Gets or sets whether the current result of the field is no longer correct (stale) due to other modifications made to the document. More...
bool	get_IsLocked ()
	Gets or sets whether the field is locked (should not recalculate its result). More...
int32_t	get_LocaleId ()
	Gets or sets the LCID of the field. More...
String	get_Result ()
	Gets or sets text that is between the field separator and field end. More...
SharedPtr< FieldSeparator >	get_Separator ()
	Gets the node that represents the field separator. Can be null. More...
SharedPtr< FieldStart >	get_Start () const
	Gets the node that represents the start of the field. More...
virtual FieldType	get_Type ()
	Gets the Microsoft Word field type. More...
String	GetFieldCode ()
	Returns text between field start and field separator (or field end if there is no separator). Both field code and field result of child fields are included. More...
String	GetFieldCode (bool includeChildFieldCodes)
	Returns text between field start and field separator (or field end if there is no separator). More...
virtual const TypeInfo &	GetType () const override
virtual bool	Is (const TypeInfo &target) const override
SharedPtr< Node >	Remove ()
	Removes the field from the document. Returns a node right after the field. If the field's end is the last child of its parent node, returns its parent paragraph. If the field is already removed, returns null. More...
void	set_IsDirty (bool value)
	Setter for get_IsDirty. More...
void	set_IsLocked (bool value)
	Setter for get_IsLocked. More...
void	set_LocaleId (int32_t value)
	Setter for get_LocaleId. More...
void	set_Result (String value)
	Setter for get_Result. More...
bool	Unlink ()
	Performs the field unlink. More...
void	Update ()
	Performs the field update. Throws if the field is being updated already. More...
void	Update (bool ignoreMergeFormat)
	Performs a field update. Throws if the field is being updated already. More...

Static Public Member Functions
static const TypeInfo &	Type ()

Member Function Documentation

get_DisplayResult()

System::String Aspose::Words::Fields::Field::get_DisplayResult

(

)

Gets the text that represents the displayed field result.

Examples

Shows how to get the real text that a field displays in the document.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
 
builder->Write(u"This document was written by ");
auto fieldAuthor = System::DynamicCast<FieldAuthor>(builder->InsertField(FieldType::FieldAuthor, true));
fieldAuthor->set_AuthorName(u"John Doe");
 
// We can use the DisplayResult property to verify what exact text
// a field would display in its place in the document.
ASSERT_EQ(String::Empty, fieldAuthor->get_DisplayResult());
 
// Fields do not maintain accurate result values in real-time.
// To make sure our fields display accurate results at any given time,
// such as right before a save operation, we need to update them manually.
fieldAuthor->Update();
 
ASSERT_EQ(u"John Doe", fieldAuthor->get_DisplayResult());
 
doc->Save(ArtifactsDir + u"Field.DisplayResult.docx");

get_End()

System::SharedPtr<Aspose::Words::Fields::FieldEnd> Aspose::Words::Fields::Field::get_End

(

)

const

Gets the node that represents the field end.

Examples

Shows how to work with a collection of fields.

void FieldCollection_()
{
    auto doc = MakeObject<Document>();
    auto builder = MakeObject<DocumentBuilder>(doc);
 
    builder->InsertField(u" DATE \\@ \"dddd, d MMMM yyyy\" ");
    builder->InsertField(u" TIME ");
    builder->InsertField(u" REVNUM ");
    builder->InsertField(u" AUTHOR  \"John Doe\" ");
    builder->InsertField(u" SUBJECT \"My Subject\" ");
    builder->InsertField(u" QUOTE \"Hello world!\" ");
    doc->UpdateFields();
 
    SharedPtr<FieldCollection> fields = doc->get_Range()->get_Fields();
 
    ASSERT_EQ(6, fields->get_Count());
 
    // Iterate over the field collection, and print contents and type
    // of every field using a custom visitor implementation.
    auto fieldVisitor = MakeObject<ExField::FieldVisitor>();
 
    {
        SharedPtr<System::Collections::Generic::IEnumerator<SharedPtr<Field>>> fieldEnumerator = fields->GetEnumerator();
        while (fieldEnumerator->MoveNext())
        {
            if (fieldEnumerator->get_Current() != nullptr)
            {
                fieldEnumerator->get_Current()->get_Start()->Accept(fieldVisitor);
                if (fieldEnumerator->get_Current()->get_Separator() != nullptr)
                {
                    fieldEnumerator->get_Current()->get_Separator()->Accept(fieldVisitor);
                }
                fieldEnumerator->get_Current()->get_End()->Accept(fieldVisitor);
            }
            else
            {
                std::cout << "There are no fields in the document." << std::endl;
            }
        }
    }
 
    std::cout << fieldVisitor->GetText() << std::endl;
}
 
class FieldVisitor : public DocumentVisitor
{
public:
    FieldVisitor()
    {
        mBuilder = MakeObject<System::Text::StringBuilder>();
    }
 
    String GetText()
    {
        return mBuilder->ToString();
    }
 
    VisitorAction VisitFieldStart(SharedPtr<FieldStart> fieldStart) override
    {
        mBuilder->AppendLine(String(u"Found field: ") + System::ObjectExt::ToString(fieldStart->get_FieldType()));
        mBuilder->AppendLine(String(u"\tField code: ") + fieldStart->GetField()->GetFieldCode());
        mBuilder->AppendLine(String(u"\tDisplayed as: ") + fieldStart->GetField()->get_Result());
 
        return VisitorAction::Continue;
    }
 
    VisitorAction VisitFieldSeparator(SharedPtr<FieldSeparator> fieldSeparator) override
    {
        mBuilder->AppendLine(String(u"\tFound separator: ") + fieldSeparator->GetText());
 
        return VisitorAction::Continue;
    }
 
    VisitorAction VisitFieldEnd(SharedPtr<FieldEnd> fieldEnd) override
    {
        mBuilder->AppendLine(String(u"End of field: ") + System::ObjectExt::ToString(fieldEnd->get_FieldType()));
 
        return VisitorAction::Continue;
    }
 
private:
    SharedPtr<System::Text::StringBuilder> mBuilder;
};

get_FieldEnd()

System::SharedPtr<Aspose::Words::Fields::FieldEnd> Aspose::Words::Fields::Field::get_FieldEnd

(

)

const

Gets the node that represents the field end.

Examples

Shows how to work with a collection of fields.

void FieldCollection_()
{
    auto doc = MakeObject<Document>();
    auto builder = MakeObject<DocumentBuilder>(doc);
 
    builder->InsertField(u" DATE \\@ \"dddd, d MMMM yyyy\" ");
    builder->InsertField(u" TIME ");
    builder->InsertField(u" REVNUM ");
    builder->InsertField(u" AUTHOR  \"John Doe\" ");
    builder->InsertField(u" SUBJECT \"My Subject\" ");
    builder->InsertField(u" QUOTE \"Hello world!\" ");
    doc->UpdateFields();
 
    SharedPtr<FieldCollection> fields = doc->get_Range()->get_Fields();
 
    ASSERT_EQ(6, fields->get_Count());
 
    // Iterate over the field collection, and print contents and type
    // of every field using a custom visitor implementation.
    auto fieldVisitor = MakeObject<ExField::FieldVisitor>();
 
    {
        SharedPtr<System::Collections::Generic::IEnumerator<SharedPtr<Field>>> fieldEnumerator = fields->GetEnumerator();
        while (fieldEnumerator->MoveNext())
        {
            if (fieldEnumerator->get_Current() != nullptr)
            {
                fieldEnumerator->get_Current()->get_Start()->Accept(fieldVisitor);
                if (fieldEnumerator->get_Current()->get_Separator() != nullptr)
                {
                    fieldEnumerator->get_Current()->get_Separator()->Accept(fieldVisitor);
                }
                fieldEnumerator->get_Current()->get_End()->Accept(fieldVisitor);
            }
            else
            {
                std::cout << "There are no fields in the document." << std::endl;
            }
        }
    }
 
    std::cout << fieldVisitor->GetText() << std::endl;
}
 
class FieldVisitor : public DocumentVisitor
{
public:
    FieldVisitor()
    {
        mBuilder = MakeObject<System::Text::StringBuilder>();
    }
 
    String GetText()
    {
        return mBuilder->ToString();
    }
 
    VisitorAction VisitFieldStart(SharedPtr<FieldStart> fieldStart) override
    {
        mBuilder->AppendLine(String(u"Found field: ") + System::ObjectExt::ToString(fieldStart->get_FieldType()));
        mBuilder->AppendLine(String(u"\tField code: ") + fieldStart->GetField()->GetFieldCode());
        mBuilder->AppendLine(String(u"\tDisplayed as: ") + fieldStart->GetField()->get_Result());
 
        return VisitorAction::Continue;
    }
 
    VisitorAction VisitFieldSeparator(SharedPtr<FieldSeparator> fieldSeparator) override
    {
        mBuilder->AppendLine(String(u"\tFound separator: ") + fieldSeparator->GetText());
 
        return VisitorAction::Continue;
    }
 
    VisitorAction VisitFieldEnd(SharedPtr<FieldEnd> fieldEnd) override
    {
        mBuilder->AppendLine(String(u"End of field: ") + System::ObjectExt::ToString(fieldEnd->get_FieldType()));
 
        return VisitorAction::Continue;
    }
 
private:
    SharedPtr<System::Text::StringBuilder> mBuilder;
};

get_FieldStart()

System::SharedPtr<Aspose::Words::Fields::FieldStart> Aspose::Words::Fields::Field::get_FieldStart

(

)

const

Gets the node that represents the start of the field.

Examples

Shows how to work with a collection of fields.

void FieldCollection_()
{
    auto doc = MakeObject<Document>();
    auto builder = MakeObject<DocumentBuilder>(doc);
 
    builder->InsertField(u" DATE \\@ \"dddd, d MMMM yyyy\" ");
    builder->InsertField(u" TIME ");
    builder->InsertField(u" REVNUM ");
    builder->InsertField(u" AUTHOR  \"John Doe\" ");
    builder->InsertField(u" SUBJECT \"My Subject\" ");
    builder->InsertField(u" QUOTE \"Hello world!\" ");
    doc->UpdateFields();
 
    SharedPtr<FieldCollection> fields = doc->get_Range()->get_Fields();
 
    ASSERT_EQ(6, fields->get_Count());
 
    // Iterate over the field collection, and print contents and type
    // of every field using a custom visitor implementation.
    auto fieldVisitor = MakeObject<ExField::FieldVisitor>();
 
    {
        SharedPtr<System::Collections::Generic::IEnumerator<SharedPtr<Field>>> fieldEnumerator = fields->GetEnumerator();
        while (fieldEnumerator->MoveNext())
        {
            if (fieldEnumerator->get_Current() != nullptr)
            {
                fieldEnumerator->get_Current()->get_Start()->Accept(fieldVisitor);
                if (fieldEnumerator->get_Current()->get_Separator() != nullptr)
                {
                    fieldEnumerator->get_Current()->get_Separator()->Accept(fieldVisitor);
                }
                fieldEnumerator->get_Current()->get_End()->Accept(fieldVisitor);
            }
            else
            {
                std::cout << "There are no fields in the document." << std::endl;
            }
        }
    }
 
    std::cout << fieldVisitor->GetText() << std::endl;
}
 
class FieldVisitor : public DocumentVisitor
{
public:
    FieldVisitor()
    {
        mBuilder = MakeObject<System::Text::StringBuilder>();
    }
 
    String GetText()
    {
        return mBuilder->ToString();
    }
 
    VisitorAction VisitFieldStart(SharedPtr<FieldStart> fieldStart) override
    {
        mBuilder->AppendLine(String(u"Found field: ") + System::ObjectExt::ToString(fieldStart->get_FieldType()));
        mBuilder->AppendLine(String(u"\tField code: ") + fieldStart->GetField()->GetFieldCode());
        mBuilder->AppendLine(String(u"\tDisplayed as: ") + fieldStart->GetField()->get_Result());
 
        return VisitorAction::Continue;
    }
 
    VisitorAction VisitFieldSeparator(SharedPtr<FieldSeparator> fieldSeparator) override
    {
        mBuilder->AppendLine(String(u"\tFound separator: ") + fieldSeparator->GetText());
 
        return VisitorAction::Continue;
    }
 
    VisitorAction VisitFieldEnd(SharedPtr<FieldEnd> fieldEnd) override
    {
        mBuilder->AppendLine(String(u"End of field: ") + System::ObjectExt::ToString(fieldEnd->get_FieldType()));
 
        return VisitorAction::Continue;
    }
 
private:
    SharedPtr<System::Text::StringBuilder> mBuilder;
};

get_Format()

System::SharedPtr<Aspose::Words::Fields::FieldFormat> Aspose::Words::Fields::Field::get_Format

(

)

Gets a FieldFormat object that provides typed access to field's formatting.

Examples

Shows how to format field results.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
 
// Use a document builder to insert a field that displays a result with no format applied.
SharedPtr<Field> field = builder->InsertField(u"= 2 + 3");
 
ASSERT_EQ(u"= 2 + 3", field->GetFieldCode());
ASSERT_EQ(u"5", field->get_Result());
 
// We can apply a format to a field's result using the field's properties.
// Below are three types of formats that we can apply to a field's result.
// 1 -  Numeric format:
SharedPtr<FieldFormat> format = field->get_Format();
format->set_NumericFormat(u"$###.00");
field->Update();
 
ASSERT_EQ(u"= 2 + 3 \\# $###.00", field->GetFieldCode());
ASSERT_EQ(u"$  5.00", field->get_Result());
 
// 2 -  Date/time format:
field = builder->InsertField(u"DATE");
format = field->get_Format();
format->set_DateTimeFormat(u"dddd, MMMM dd, yyyy");
field->Update();
 
ASSERT_EQ(u"DATE \\@ \"dddd, MMMM dd, yyyy\"", field->GetFieldCode());
std::cout << "Today's date, in " << format->get_DateTimeFormat() << " format:\n\t" << field->get_Result() << std::endl;
 
// 3 -  General format:
field = builder->InsertField(u"= 25 + 33");
format = field->get_Format();
format->get_GeneralFormats()->Add(GeneralFormat::LowercaseRoman);
format->get_GeneralFormats()->Add(GeneralFormat::Upper);
field->Update();
 
int index = 0;
{
    SharedPtr<System::Collections::Generic::IEnumerator<GeneralFormat>> generalFormatEnumerator = format->get_GeneralFormats()->GetEnumerator();
    while (generalFormatEnumerator->MoveNext())
    {
        std::cout << String::Format(u"General format index {0}: {1}", index++, generalFormatEnumerator->get_Current()) << std::endl;
    }
}
 
ASSERT_EQ(u"= 25 + 33 \\* roman \\* Upper", field->GetFieldCode());
ASSERT_EQ(u"LVIII", field->get_Result());
ASSERT_EQ(2, format->get_GeneralFormats()->get_Count());
ASSERT_EQ(GeneralFormat::LowercaseRoman, format->get_GeneralFormats()->idx_get(0));
 
// We can remove our formats to revert the field's result to its original form.
format->get_GeneralFormats()->Remove(GeneralFormat::LowercaseRoman);
format->get_GeneralFormats()->RemoveAt(0);
ASSERT_EQ(0, format->get_GeneralFormats()->get_Count());
field->Update();
 
ASSERT_EQ(u"= 25 + 33  ", field->GetFieldCode());
ASSERT_EQ(u"58", field->get_Result());
ASSERT_EQ(0, format->get_GeneralFormats()->get_Count());

get_IsDirty()

bool Aspose::Words::Fields::Field::get_IsDirty

(

)

Gets or sets whether the current result of the field is no longer correct (stale) due to other modifications made to the document.

Examples

Shows how to use special property for updating field result.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
 
// Give the document's built-in "Author" property value, and then display it with a field.
doc->get_BuiltInDocumentProperties()->set_Author(u"John Doe");
auto field = System::DynamicCast<FieldAuthor>(builder->InsertField(FieldType::FieldAuthor, true));
 
ASSERT_FALSE(field->get_IsDirty());
ASSERT_EQ(u"John Doe", field->get_Result());
 
// Update the property. The field still displays the old value.
doc->get_BuiltInDocumentProperties()->set_Author(u"John & Jane Doe");
 
ASSERT_EQ(u"John Doe", field->get_Result());
 
// Since the field's value is out of date, we can mark it as "dirty".
// This value will stay out of date until we update the field manually with the Field.Update() method.
field->set_IsDirty(true);
 
{
    auto docStream = MakeObject<System::IO::MemoryStream>();
    // If we save without calling an update method,
    // the field will keep displaying the out of date value in the output document.
    doc->Save(docStream, SaveFormat::Docx);
 
    // The LoadOptions object has an option to update all fields
    // marked as "dirty" when loading the document.
    auto options = MakeObject<Loading::LoadOptions>();
    options->set_UpdateDirtyFields(updateDirtyFields);
    doc = MakeObject<Document>(docStream, options);
 
    ASSERT_EQ(u"John & Jane Doe", doc->get_BuiltInDocumentProperties()->get_Author());
 
    field = System::DynamicCast<FieldAuthor>(doc->get_Range()->get_Fields()->idx_get(0));
 
    // Updating dirty fields like this automatically set their "IsDirty" flag to false.
    if (updateDirtyFields)
    {
        ASSERT_EQ(u"John & Jane Doe", field->get_Result());
        ASSERT_FALSE(field->get_IsDirty());
    }
    else
    {
        ASSERT_EQ(u"John Doe", field->get_Result());
        ASSERT_TRUE(field->get_IsDirty());
    }
}

get_IsLocked()

bool Aspose::Words::Fields::Field::get_IsLocked

(

)

Gets or sets whether the field is locked (should not recalculate its result).

Examples

Shows how to work with a FieldStart node.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
 
auto field = System::DynamicCast<FieldDate>(builder->InsertField(FieldType::FieldDate, true));
field->get_Format()->set_DateTimeFormat(u"dddd, MMMM dd, yyyy");
field->Update();
 
SharedPtr<FieldChar> fieldStart = field->get_Start();
 
ASSERT_EQ(FieldType::FieldDate, fieldStart->get_FieldType());
ASPOSE_ASSERT_EQ(false, fieldStart->get_IsDirty());
ASPOSE_ASSERT_EQ(false, fieldStart->get_IsLocked());
 
// Retrieve the facade object which represents the field in the document.
field = System::DynamicCast<FieldDate>(fieldStart->GetField());
 
ASPOSE_ASSERT_EQ(false, field->get_IsLocked());
ASSERT_EQ(u" DATE  \\@ \"dddd, MMMM dd, yyyy\"", field->GetFieldCode());
 
// Update the field to show the current date.
field->Update();

get_LocaleId()

int32_t Aspose::Words::Fields::Field::get_LocaleId

(

)

Gets or sets the LCID of the field.

See also

Aspose::Words::Fields::FieldUpdateCultureSource::FieldCode

Examples

Shows how to insert a field and work with its locale.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
 
// Insert a DATE field, and then print the date it will display.
// Your thread's current culture determines the formatting of the date.
SharedPtr<Field> field = builder->InsertField(u"DATE");
std::cout << "Today's date, as displayed in the \"" << System::Globalization::CultureInfo::get_CurrentCulture()->get_EnglishName()
          << "\" culture: " << field->get_Result() << std::endl;
 
ASSERT_EQ(1033, field->get_LocaleId());
 
// Changing the culture of our thread will impact the result of the DATE field.
// Another way to get the DATE field to display a date in a different culture is to use its LocaleId property.
// This way allows us to avoid changing the thread's culture to get this effect.
doc->get_FieldOptions()->set_FieldUpdateCultureSource(FieldUpdateCultureSource::FieldCode);
auto de = MakeObject<System::Globalization::CultureInfo>(u"de-DE");
field->set_LocaleId(de->get_LCID());
field->Update();
 
std::cout << "Today's date, as displayed according to the \""
          << System::Globalization::CultureInfo::GetCultureInfo(field->get_LocaleId())->get_EnglishName() << "\" culture: " << field->get_Result()
          << std::endl;

get_Result()

System::String Aspose::Words::Fields::Field::get_Result

(

)

Gets or sets text that is between the field separator and field end.

Examples

Shows how to insert a field into a document using a field code.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
 
SharedPtr<Field> field = builder->InsertField(u"DATE \\@ \"dddd, MMMM dd, yyyy\"");
 
ASSERT_EQ(FieldType::FieldDate, field->get_Type());
ASSERT_EQ(u"DATE \\@ \"dddd, MMMM dd, yyyy\"", field->GetFieldCode());
 
// This overload of the InsertField method automatically updates inserted fields.
ASSERT_LE(System::Math::Abs((System::DateTime::Parse(field->get_Result()) - System::DateTime::get_Today()).get_Hours()), 24);

get_Separator()

System::SharedPtr<Aspose::Words::Fields::FieldSeparator> Aspose::Words::Fields::Field::get_Separator

(

)

Gets the node that represents the field separator. Can be null.

Examples

Shows how to work with a collection of fields.

void FieldCollection_()
{
    auto doc = MakeObject<Document>();
    auto builder = MakeObject<DocumentBuilder>(doc);
 
    builder->InsertField(u" DATE \\@ \"dddd, d MMMM yyyy\" ");
    builder->InsertField(u" TIME ");
    builder->InsertField(u" REVNUM ");
    builder->InsertField(u" AUTHOR  \"John Doe\" ");
    builder->InsertField(u" SUBJECT \"My Subject\" ");
    builder->InsertField(u" QUOTE \"Hello world!\" ");
    doc->UpdateFields();
 
    SharedPtr<FieldCollection> fields = doc->get_Range()->get_Fields();
 
    ASSERT_EQ(6, fields->get_Count());
 
    // Iterate over the field collection, and print contents and type
    // of every field using a custom visitor implementation.
    auto fieldVisitor = MakeObject<ExField::FieldVisitor>();
 
    {
        SharedPtr<System::Collections::Generic::IEnumerator<SharedPtr<Field>>> fieldEnumerator = fields->GetEnumerator();
        while (fieldEnumerator->MoveNext())
        {
            if (fieldEnumerator->get_Current() != nullptr)
            {
                fieldEnumerator->get_Current()->get_Start()->Accept(fieldVisitor);
                if (fieldEnumerator->get_Current()->get_Separator() != nullptr)
                {
                    fieldEnumerator->get_Current()->get_Separator()->Accept(fieldVisitor);
                }
                fieldEnumerator->get_Current()->get_End()->Accept(fieldVisitor);
            }
            else
            {
                std::cout << "There are no fields in the document." << std::endl;
            }
        }
    }
 
    std::cout << fieldVisitor->GetText() << std::endl;
}
 
class FieldVisitor : public DocumentVisitor
{
public:
    FieldVisitor()
    {
        mBuilder = MakeObject<System::Text::StringBuilder>();
    }
 
    String GetText()
    {
        return mBuilder->ToString();
    }
 
    VisitorAction VisitFieldStart(SharedPtr<FieldStart> fieldStart) override
    {
        mBuilder->AppendLine(String(u"Found field: ") + System::ObjectExt::ToString(fieldStart->get_FieldType()));
        mBuilder->AppendLine(String(u"\tField code: ") + fieldStart->GetField()->GetFieldCode());
        mBuilder->AppendLine(String(u"\tDisplayed as: ") + fieldStart->GetField()->get_Result());
 
        return VisitorAction::Continue;
    }
 
    VisitorAction VisitFieldSeparator(SharedPtr<FieldSeparator> fieldSeparator) override
    {
        mBuilder->AppendLine(String(u"\tFound separator: ") + fieldSeparator->GetText());
 
        return VisitorAction::Continue;
    }
 
    VisitorAction VisitFieldEnd(SharedPtr<FieldEnd> fieldEnd) override
    {
        mBuilder->AppendLine(String(u"End of field: ") + System::ObjectExt::ToString(fieldEnd->get_FieldType()));
 
        return VisitorAction::Continue;
    }
 
private:
    SharedPtr<System::Text::StringBuilder> mBuilder;
};

get_Start()

System::SharedPtr<Aspose::Words::Fields::FieldStart> Aspose::Words::Fields::Field::get_Start

(

)

const

Gets the node that represents the start of the field.

Examples

Shows how to work with a collection of fields.

void FieldCollection_()
{
    auto doc = MakeObject<Document>();
    auto builder = MakeObject<DocumentBuilder>(doc);
 
    builder->InsertField(u" DATE \\@ \"dddd, d MMMM yyyy\" ");
    builder->InsertField(u" TIME ");
    builder->InsertField(u" REVNUM ");
    builder->InsertField(u" AUTHOR  \"John Doe\" ");
    builder->InsertField(u" SUBJECT \"My Subject\" ");
    builder->InsertField(u" QUOTE \"Hello world!\" ");
    doc->UpdateFields();
 
    SharedPtr<FieldCollection> fields = doc->get_Range()->get_Fields();
 
    ASSERT_EQ(6, fields->get_Count());
 
    // Iterate over the field collection, and print contents and type
    // of every field using a custom visitor implementation.
    auto fieldVisitor = MakeObject<ExField::FieldVisitor>();
 
    {
        SharedPtr<System::Collections::Generic::IEnumerator<SharedPtr<Field>>> fieldEnumerator = fields->GetEnumerator();
        while (fieldEnumerator->MoveNext())
        {
            if (fieldEnumerator->get_Current() != nullptr)
            {
                fieldEnumerator->get_Current()->get_Start()->Accept(fieldVisitor);
                if (fieldEnumerator->get_Current()->get_Separator() != nullptr)
                {
                    fieldEnumerator->get_Current()->get_Separator()->Accept(fieldVisitor);
                }
                fieldEnumerator->get_Current()->get_End()->Accept(fieldVisitor);
            }
            else
            {
                std::cout << "There are no fields in the document." << std::endl;
            }
        }
    }
 
    std::cout << fieldVisitor->GetText() << std::endl;
}
 
class FieldVisitor : public DocumentVisitor
{
public:
    FieldVisitor()
    {
        mBuilder = MakeObject<System::Text::StringBuilder>();
    }
 
    String GetText()
    {
        return mBuilder->ToString();
    }
 
    VisitorAction VisitFieldStart(SharedPtr<FieldStart> fieldStart) override
    {
        mBuilder->AppendLine(String(u"Found field: ") + System::ObjectExt::ToString(fieldStart->get_FieldType()));
        mBuilder->AppendLine(String(u"\tField code: ") + fieldStart->GetField()->GetFieldCode());
        mBuilder->AppendLine(String(u"\tDisplayed as: ") + fieldStart->GetField()->get_Result());
 
        return VisitorAction::Continue;
    }
 
    VisitorAction VisitFieldSeparator(SharedPtr<FieldSeparator> fieldSeparator) override
    {
        mBuilder->AppendLine(String(u"\tFound separator: ") + fieldSeparator->GetText());
 
        return VisitorAction::Continue;
    }
 
    VisitorAction VisitFieldEnd(SharedPtr<FieldEnd> fieldEnd) override
    {
        mBuilder->AppendLine(String(u"End of field: ") + System::ObjectExt::ToString(fieldEnd->get_FieldType()));
 
        return VisitorAction::Continue;
    }
 
private:
    SharedPtr<System::Text::StringBuilder> mBuilder;
};

get_Type()

virtual Aspose::Words::Fields::FieldType Aspose::Words::Fields::Field::get_Type ( )

virtual

Gets the Microsoft Word field type.

Examples

Shows how to insert a field into a document using a field code.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
 
SharedPtr<Field> field = builder->InsertField(u"DATE \\@ \"dddd, MMMM dd, yyyy\"");
 
ASSERT_EQ(FieldType::FieldDate, field->get_Type());
ASSERT_EQ(u"DATE \\@ \"dddd, MMMM dd, yyyy\"", field->GetFieldCode());
 
// This overload of the InsertField method automatically updates inserted fields.
ASSERT_LE(System::Math::Abs((System::DateTime::Parse(field->get_Result()) - System::DateTime::get_Today()).get_Hours()), 24);

Reimplemented in Aspose::Words::Fields::FieldMergeField.

GetFieldCode() [1/2]

System::String Aspose::Words::Fields::Field::GetFieldCode

(

)

Returns text between field start and field separator (or field end if there is no separator). Both field code and field result of child fields are included.

Examples

Shows how to insert a field into a document using a field code.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
 
SharedPtr<Field> field = builder->InsertField(u"DATE \\@ \"dddd, MMMM dd, yyyy\"");
 
ASSERT_EQ(FieldType::FieldDate, field->get_Type());
ASSERT_EQ(u"DATE \\@ \"dddd, MMMM dd, yyyy\"", field->GetFieldCode());
 
// This overload of the InsertField method automatically updates inserted fields.
ASSERT_LE(System::Math::Abs((System::DateTime::Parse(field->get_Result()) - System::DateTime::get_Today()).get_Hours()), 24);

Shows how to get a field's field code.

// Open a document which contains a MERGEFIELD inside an IF field.
auto doc = MakeObject<Document>(MyDir + u"Nested fields.docx");
auto fieldIf = System::DynamicCast<FieldIf>(doc->get_Range()->get_Fields()->idx_get(0));
 
// There are two ways of getting a field's field code:
// 1 -  Omit its inner fields:
ASSERT_EQ(u" IF  > 0 \" (surplus of ) \" \"\" ", fieldIf->GetFieldCode(false));
 
// 2 -  Include its inner fields:
ASSERT_EQ(String::Format(u" IF \u0013 MERGEFIELD NetIncome \u0014\u0015 > 0 \" (surplus of \u0013 MERGEFIELD  NetIncome \\f $ \u0014\u0015) \" \"\" "),
          fieldIf->GetFieldCode(true));
 
// By default, the GetFieldCode method displays inner fields.
ASSERT_EQ(fieldIf->GetFieldCode(), fieldIf->GetFieldCode(true));

GetFieldCode() [2/2]

System::String Aspose::Words::Fields::Field::GetFieldCode

(

bool

includeChildFieldCodes

)

Returns text between field start and field separator (or field end if there is no separator).

Parameters

includeChildFieldCodes

True if child field codes should be included.

Examples

Shows how to get a field's field code.

// Open a document which contains a MERGEFIELD inside an IF field.
auto doc = MakeObject<Document>(MyDir + u"Nested fields.docx");
auto fieldIf = System::DynamicCast<FieldIf>(doc->get_Range()->get_Fields()->idx_get(0));
 
// There are two ways of getting a field's field code:
// 1 -  Omit its inner fields:
ASSERT_EQ(u" IF  > 0 \" (surplus of ) \" \"\" ", fieldIf->GetFieldCode(false));
 
// 2 -  Include its inner fields:
ASSERT_EQ(String::Format(u" IF \u0013 MERGEFIELD NetIncome \u0014\u0015 > 0 \" (surplus of \u0013 MERGEFIELD  NetIncome \\f $ \u0014\u0015) \" \"\" "),
          fieldIf->GetFieldCode(true));
 
// By default, the GetFieldCode method displays inner fields.
ASSERT_EQ(fieldIf->GetFieldCode(), fieldIf->GetFieldCode(true));

GetType()

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

overridevirtual

Reimplemented from System::Object.

Reimplemented in Aspose::Words::Fields::FieldXE, Aspose::Words::Fields::FieldUserName, Aspose::Words::Fields::FieldUserInitials, Aspose::Words::Fields::FieldUserAddress, Aspose::Words::Fields::FieldUnknown, Aspose::Words::Fields::FieldToc, Aspose::Words::Fields::FieldToa, Aspose::Words::Fields::FieldTitle, Aspose::Words::Fields::FieldTime, Aspose::Words::Fields::FieldTemplate, Aspose::Words::Fields::FieldTC, Aspose::Words::Fields::FieldTA, Aspose::Words::Fields::FieldSymbol, Aspose::Words::Fields::FieldSubject, Aspose::Words::Fields::FieldStyleRef, Aspose::Words::Fields::FieldSkipIf, Aspose::Words::Fields::FieldShape, Aspose::Words::Fields::FieldSet, Aspose::Words::Fields::FieldSeq, Aspose::Words::Fields::FieldSectionPages, Aspose::Words::Fields::FieldSection, Aspose::Words::Fields::FieldSaveDate, Aspose::Words::Fields::FieldRevNum, Aspose::Words::Fields::FieldRef, Aspose::Words::Fields::FieldRD, Aspose::Words::Fields::FieldQuote, Aspose::Words::Fields::FieldPrivate, Aspose::Words::Fields::FieldPrintDate, Aspose::Words::Fields::FieldPrint, Aspose::Words::Fields::FieldPageRef, Aspose::Words::Fields::FieldPage, Aspose::Words::Fields::FieldOcx, Aspose::Words::Fields::FieldNumWords, Aspose::Words::Fields::FieldNumPages, Aspose::Words::Fields::FieldNumChars, Aspose::Words::Fields::FieldNoteRef, Aspose::Words::Fields::FieldNextIf, Aspose::Words::Fields::FieldNext, Aspose::Words::Fields::FieldMergeSeq, Aspose::Words::Fields::FieldMergeRec, Aspose::Words::Fields::FieldMergeField, Aspose::Words::Fields::FieldMergeBarcode, Aspose::Words::Fields::FieldMacroButton, Aspose::Words::Fields::FieldListNum, Aspose::Words::Fields::FieldLink, Aspose::Words::Fields::FieldLastSavedBy, Aspose::Words::Fields::FieldKeywords, Aspose::Words::Fields::FieldInfo, Aspose::Words::Fields::FieldIndex, Aspose::Words::Fields::FieldIncludeText, Aspose::Words::Fields::FieldIncludePicture, Aspose::Words::Fields::FieldInclude, Aspose::Words::Fields::FieldImport, Aspose::Words::Fields::FieldIf, Aspose::Words::Fields::FieldHyperlink, Aspose::Words::Fields::FieldGreetingLine, Aspose::Words::Fields::FieldGoToButton, Aspose::Words::Fields::FieldGlossary, Aspose::Words::Fields::FieldFormula, Aspose::Words::Fields::FieldFormText, Aspose::Words::Fields::FieldFormDropDown, Aspose::Words::Fields::FieldFormCheckBox, Aspose::Words::Fields::FieldFootnoteRef, Aspose::Words::Fields::FieldFillIn, Aspose::Words::Fields::FieldFileSize, Aspose::Words::Fields::FieldFileName, Aspose::Words::Fields::FieldEQ, Aspose::Words::Fields::FieldEmbed, Aspose::Words::Fields::FieldEditTime, Aspose::Words::Fields::FieldDocVariable, Aspose::Words::Fields::FieldDocProperty, Aspose::Words::Fields::FieldDisplayBarcode, Aspose::Words::Fields::FieldDdeAuto, Aspose::Words::Fields::FieldDde, Aspose::Words::Fields::FieldDate, Aspose::Words::Fields::FieldDatabase, Aspose::Words::Fields::FieldData, Aspose::Words::Fields::FieldCreateDate, Aspose::Words::Fields::FieldCompare, Aspose::Words::Fields::FieldComments, Aspose::Words::Fields::FieldCitation, Aspose::Words::Fields::FieldBidiOutline, Aspose::Words::Fields::FieldBibliography, Aspose::Words::Fields::FieldBarcode, Aspose::Words::Fields::FieldAutoTextList, Aspose::Words::Fields::FieldAutoText, Aspose::Words::Fields::FieldAutoNumOut, Aspose::Words::Fields::FieldAutoNumLgl, Aspose::Words::Fields::FieldAutoNum, Aspose::Words::Fields::FieldAuthor, Aspose::Words::Fields::FieldAsk, Aspose::Words::Fields::FieldAdvance, Aspose::Words::Fields::FieldAddressBlock, and Aspose::Words::Fields::FieldAddIn.

Is()

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

overridevirtual

Reimplemented from System::Object.

Reimplemented in Aspose::Words::Fields::FieldXE, Aspose::Words::Fields::FieldUserName, Aspose::Words::Fields::FieldUserInitials, Aspose::Words::Fields::FieldUserAddress, Aspose::Words::Fields::FieldUnknown, Aspose::Words::Fields::FieldToc, Aspose::Words::Fields::FieldToa, Aspose::Words::Fields::FieldTitle, Aspose::Words::Fields::FieldTime, Aspose::Words::Fields::FieldTemplate, Aspose::Words::Fields::FieldTC, Aspose::Words::Fields::FieldTA, Aspose::Words::Fields::FieldSymbol, Aspose::Words::Fields::FieldSubject, Aspose::Words::Fields::FieldStyleRef, Aspose::Words::Fields::FieldSkipIf, Aspose::Words::Fields::FieldShape, Aspose::Words::Fields::FieldSet, Aspose::Words::Fields::FieldSeq, Aspose::Words::Fields::FieldSectionPages, Aspose::Words::Fields::FieldSection, Aspose::Words::Fields::FieldSaveDate, Aspose::Words::Fields::FieldRevNum, Aspose::Words::Fields::FieldRef, Aspose::Words::Fields::FieldRD, Aspose::Words::Fields::FieldQuote, Aspose::Words::Fields::FieldPrivate, Aspose::Words::Fields::FieldPrintDate, Aspose::Words::Fields::FieldPrint, Aspose::Words::Fields::FieldPageRef, Aspose::Words::Fields::FieldPage, Aspose::Words::Fields::FieldOcx, Aspose::Words::Fields::FieldNumWords, Aspose::Words::Fields::FieldNumPages, Aspose::Words::Fields::FieldNumChars, Aspose::Words::Fields::FieldNoteRef, Aspose::Words::Fields::FieldNextIf, Aspose::Words::Fields::FieldNext, Aspose::Words::Fields::FieldMergeSeq, Aspose::Words::Fields::FieldMergeRec, Aspose::Words::Fields::FieldMergeField, Aspose::Words::Fields::FieldMergeBarcode, Aspose::Words::Fields::FieldMacroButton, Aspose::Words::Fields::FieldListNum, Aspose::Words::Fields::FieldLink, Aspose::Words::Fields::FieldLastSavedBy, Aspose::Words::Fields::FieldKeywords, Aspose::Words::Fields::FieldInfo, Aspose::Words::Fields::FieldIndex, Aspose::Words::Fields::FieldIncludeText, Aspose::Words::Fields::FieldIncludePicture, Aspose::Words::Fields::FieldInclude, Aspose::Words::Fields::FieldImport, Aspose::Words::Fields::FieldIf, Aspose::Words::Fields::FieldHyperlink, Aspose::Words::Fields::FieldGreetingLine, Aspose::Words::Fields::FieldGoToButton, Aspose::Words::Fields::FieldGlossary, Aspose::Words::Fields::FieldFormula, Aspose::Words::Fields::FieldFormText, Aspose::Words::Fields::FieldFormDropDown, Aspose::Words::Fields::FieldFormCheckBox, Aspose::Words::Fields::FieldFootnoteRef, Aspose::Words::Fields::FieldFillIn, Aspose::Words::Fields::FieldFileSize, Aspose::Words::Fields::FieldFileName, Aspose::Words::Fields::FieldEQ, Aspose::Words::Fields::FieldEmbed, Aspose::Words::Fields::FieldEditTime, Aspose::Words::Fields::FieldDocVariable, Aspose::Words::Fields::FieldDocProperty, Aspose::Words::Fields::FieldDisplayBarcode, Aspose::Words::Fields::FieldDdeAuto, Aspose::Words::Fields::FieldDde, Aspose::Words::Fields::FieldDate, Aspose::Words::Fields::FieldDatabase, Aspose::Words::Fields::FieldData, Aspose::Words::Fields::FieldCreateDate, Aspose::Words::Fields::FieldCompare, Aspose::Words::Fields::FieldComments, Aspose::Words::Fields::FieldCitation, Aspose::Words::Fields::FieldBidiOutline, Aspose::Words::Fields::FieldBibliography, Aspose::Words::Fields::FieldBarcode, Aspose::Words::Fields::FieldAutoTextList, Aspose::Words::Fields::FieldAutoText, Aspose::Words::Fields::FieldAutoNumOut, Aspose::Words::Fields::FieldAutoNumLgl, Aspose::Words::Fields::FieldAutoNum, Aspose::Words::Fields::FieldAuthor, Aspose::Words::Fields::FieldAsk, Aspose::Words::Fields::FieldAdvance, Aspose::Words::Fields::FieldAddressBlock, and Aspose::Words::Fields::FieldAddIn.

Remove()

System::SharedPtr<Aspose::Words::Node> Aspose::Words::Fields::Field::Remove

(

)

Removes the field from the document. Returns a node right after the field. If the field's end is the last child of its parent node, returns its parent paragraph. If the field is already removed, returns null.

Examples

Shows how to remove fields from a field collection.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
 
builder->InsertField(u" DATE \\@ \"dddd, d MMMM yyyy\" ");
builder->InsertField(u" TIME ");
builder->InsertField(u" REVNUM ");
builder->InsertField(u" AUTHOR  \"John Doe\" ");
builder->InsertField(u" SUBJECT \"My Subject\" ");
builder->InsertField(u" QUOTE \"Hello world!\" ");
doc->UpdateFields();
 
SharedPtr<FieldCollection> fields = doc->get_Range()->get_Fields();
 
ASSERT_EQ(6, fields->get_Count());
 
// Below are four ways of removing fields from a field collection.
// 1 -  Get a field to remove itself:
fields->idx_get(0)->Remove();
ASSERT_EQ(5, fields->get_Count());
 
// 2 -  Get the collection to remove a field that we pass to its removal method:
SharedPtr<Field> lastField = fields->idx_get(3);
fields->Remove(lastField);
ASSERT_EQ(4, fields->get_Count());
 
// 3 -  Remove a field from a collection at an index:
fields->RemoveAt(2);
ASSERT_EQ(3, fields->get_Count());
 
// 4 -  Remove all the fields from the collection at once:
fields->Clear();
ASSERT_EQ(0, fields->get_Count());

Shows how to process PRIVATE fields.

void FieldPrivate_()
{
    // Open a Corel WordPerfect document which we have converted to .docx format.
    auto doc = MakeObject<Document>(MyDir + u"Field sample - PRIVATE.docx");
 
    // WordPerfect 5.x/6.x documents like the one we have loaded may contain PRIVATE fields.
    // Microsoft Word preserves PRIVATE fields during load/save operations,
    // but provides no functionality for them.
    auto field = System::DynamicCast<FieldPrivate>(doc->get_Range()->get_Fields()->idx_get(0));
 
    ASSERT_EQ(u" PRIVATE \"My value\" ", field->GetFieldCode());
    ASSERT_EQ(FieldType::FieldPrivate, field->get_Type());
 
    // We can also insert PRIVATE fields using a document builder.
    auto builder = MakeObject<DocumentBuilder>(doc);
    builder->InsertField(FieldType::FieldPrivate, true);
 
    // These fields are not a viable way of protecting sensitive information.
    // Unless backward compatibility with older versions of WordPerfect is essential,
    // we can safely remove these fields. We can do this using a DocumentVisiitor implementation.
    ASSERT_EQ(2, doc->get_Range()->get_Fields()->get_Count());
 
    auto remover = MakeObject<ExField::FieldPrivateRemover>();
    doc->Accept(remover);
 
    ASSERT_EQ(2, remover->GetFieldsRemovedCount());
    ASSERT_EQ(0, doc->get_Range()->get_Fields()->get_Count());
}
 
class FieldPrivateRemover : public DocumentVisitor
{
public:
    FieldPrivateRemover() : mFieldsRemovedCount(0)
    {
        mFieldsRemovedCount = 0;
    }
 
    int GetFieldsRemovedCount()
    {
        return mFieldsRemovedCount;
    }
 
    VisitorAction VisitFieldEnd(SharedPtr<FieldEnd> fieldEnd) override
    {
        if (fieldEnd->get_FieldType() == FieldType::FieldPrivate)
        {
            fieldEnd->GetField()->Remove();
            mFieldsRemovedCount++;
        }
 
        return VisitorAction::Continue;
    }
 
private:
    int mFieldsRemovedCount;
};

set_IsDirty()

void Aspose::Words::Fields::Field::set_IsDirty

(

bool

value

)

Setter for Aspose::Words::Fields::Field::get_IsDirty.

set_IsLocked()

void Aspose::Words::Fields::Field::set_IsLocked

(

bool

value

)

Setter for Aspose::Words::Fields::Field::get_IsLocked.

set_LocaleId()

void Aspose::Words::Fields::Field::set_LocaleId

(

int32_t

value

)

Setter for Aspose::Words::Fields::Field::get_LocaleId.

set_Result()

void Aspose::Words::Fields::Field::set_Result

(

System::String

value

)

Setter for Aspose::Words::Fields::Field::get_Result.

Type()

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

static

Unlink()

bool Aspose::Words::Fields::Field::Unlink

(

)

Performs the field unlink.

Replaces the field with its most recent result.

Some fields, such as XE (Index Entry) fields and SEQ (Sequence) fields, cannot be unlinked.

Returns

True if the field has been unlinked, otherwise false.

Examples

Shows how to unlink a field.

auto doc = MakeObject<Document>(MyDir + u"Linked fields.docx");
doc->get_Range()->get_Fields()->idx_get(1)->Unlink();

Update() [1/2]

void Aspose::Words::Fields::Field::Update

(

)

Performs the field update. Throws if the field is being updated already.

Examples

Shows how to insert a field into a document using FieldType.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
 
// Insert two fields while passing a flag which determines whether to update them as the builder inserts them.
// In some cases, updating fields could be computationally expensive, and it may be a good idea to defer the update.
doc->get_BuiltInDocumentProperties()->set_Author(u"John Doe");
builder->Write(u"This document was written by ");
builder->InsertField(FieldType::FieldAuthor, updateInsertedFieldsImmediately);
 
builder->InsertParagraph();
builder->Write(u"\nThis is page ");
builder->InsertField(FieldType::FieldPage, updateInsertedFieldsImmediately);
 
ASSERT_EQ(u" AUTHOR ", doc->get_Range()->get_Fields()->idx_get(0)->GetFieldCode());
ASSERT_EQ(u" PAGE ", doc->get_Range()->get_Fields()->idx_get(1)->GetFieldCode());
 
if (updateInsertedFieldsImmediately)
{
    ASSERT_EQ(u"John Doe", doc->get_Range()->get_Fields()->idx_get(0)->get_Result());
    ASSERT_EQ(u"1", doc->get_Range()->get_Fields()->idx_get(1)->get_Result());
}
else
{
    ASSERT_EQ(String::Empty, doc->get_Range()->get_Fields()->idx_get(0)->get_Result());
    ASSERT_EQ(String::Empty, doc->get_Range()->get_Fields()->idx_get(1)->get_Result());
 
    // We will need to update these fields using the update methods manually.
    doc->get_Range()->get_Fields()->idx_get(0)->Update();
 
    ASSERT_EQ(u"John Doe", doc->get_Range()->get_Fields()->idx_get(0)->get_Result());
 
    doc->UpdateFields();
 
    ASSERT_EQ(u"1", doc->get_Range()->get_Fields()->idx_get(1)->get_Result());
}

Shows how to format field results.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
 
// Use a document builder to insert a field that displays a result with no format applied.
SharedPtr<Field> field = builder->InsertField(u"= 2 + 3");
 
ASSERT_EQ(u"= 2 + 3", field->GetFieldCode());
ASSERT_EQ(u"5", field->get_Result());
 
// We can apply a format to a field's result using the field's properties.
// Below are three types of formats that we can apply to a field's result.
// 1 -  Numeric format:
SharedPtr<FieldFormat> format = field->get_Format();
format->set_NumericFormat(u"$###.00");
field->Update();
 
ASSERT_EQ(u"= 2 + 3 \\# $###.00", field->GetFieldCode());
ASSERT_EQ(u"$  5.00", field->get_Result());
 
// 2 -  Date/time format:
field = builder->InsertField(u"DATE");
format = field->get_Format();
format->set_DateTimeFormat(u"dddd, MMMM dd, yyyy");
field->Update();
 
ASSERT_EQ(u"DATE \\@ \"dddd, MMMM dd, yyyy\"", field->GetFieldCode());
std::cout << "Today's date, in " << format->get_DateTimeFormat() << " format:\n\t" << field->get_Result() << std::endl;
 
// 3 -  General format:
field = builder->InsertField(u"= 25 + 33");
format = field->get_Format();
format->get_GeneralFormats()->Add(GeneralFormat::LowercaseRoman);
format->get_GeneralFormats()->Add(GeneralFormat::Upper);
field->Update();
 
int index = 0;
{
    SharedPtr<System::Collections::Generic::IEnumerator<GeneralFormat>> generalFormatEnumerator = format->get_GeneralFormats()->GetEnumerator();
    while (generalFormatEnumerator->MoveNext())
    {
        std::cout << String::Format(u"General format index {0}: {1}", index++, generalFormatEnumerator->get_Current()) << std::endl;
    }
}
 
ASSERT_EQ(u"= 25 + 33 \\* roman \\* Upper", field->GetFieldCode());
ASSERT_EQ(u"LVIII", field->get_Result());
ASSERT_EQ(2, format->get_GeneralFormats()->get_Count());
ASSERT_EQ(GeneralFormat::LowercaseRoman, format->get_GeneralFormats()->idx_get(0));
 
// We can remove our formats to revert the field's result to its original form.
format->get_GeneralFormats()->Remove(GeneralFormat::LowercaseRoman);
format->get_GeneralFormats()->RemoveAt(0);
ASSERT_EQ(0, format->get_GeneralFormats()->get_Count());
field->Update();
 
ASSERT_EQ(u"= 25 + 33  ", field->GetFieldCode());
ASSERT_EQ(u"58", field->get_Result());
ASSERT_EQ(0, format->get_GeneralFormats()->get_Count());

Update() [2/2]

void Aspose::Words::Fields::Field::Update

(

bool

ignoreMergeFormat

)

Performs a field update. Throws if the field is being updated already.

Parameters

ignoreMergeFormat

If true then direct field result formatting is abandoned, regardless of the MERGEFORMAT switch, otherwise normal update is performed.

Examples

Shows how to preserve or discard INCLUDEPICTURE fields when loading a document.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
 
auto includePicture = System::DynamicCast<FieldIncludePicture>(builder->InsertField(FieldType::FieldIncludePicture, true));
includePicture->set_SourceFullName(ImageDir + u"Transparent background logo.png");
includePicture->Update(true);
 
{
    auto docStream = MakeObject<System::IO::MemoryStream>();
    doc->Save(docStream, MakeObject<OoxmlSaveOptions>(SaveFormat::Docx));
 
    // We can set a flag in a LoadOptions object to decide whether to convert all INCLUDEPICTURE fields
    // into image shapes when loading a document that contains them.
    auto loadOptions = MakeObject<Loading::LoadOptions>();
    loadOptions->set_PreserveIncludePictureField(preserveIncludePictureField);
 
    doc = MakeObject<Document>(docStream, loadOptions);
 
    if (preserveIncludePictureField)
    {
        ASSERT_TRUE(doc->get_Range()->get_Fields()->LINQ_Any([](SharedPtr<Field> f) { return f->get_Type() == FieldType::FieldIncludePicture; }));
 
        doc->UpdateFields();
        doc->Save(ArtifactsDir + u"Field.PreserveIncludePicture.docx");
    }
    else
    {
        ASSERT_FALSE(doc->get_Range()->get_Fields()->LINQ_Any([](SharedPtr<Field> f) { return f->get_Type() == FieldType::FieldIncludePicture; }));
    }
}