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

Detailed Description

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

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Insert a simple Date field into the document
// When we insert a field through the DocumentBuilder class we can get the
// special Field object which contains information about the field
SharedPtr<Field> dateField = builder->InsertField(u"DATE \\* MERGEFORMAT");
// Update this particular field in the document so we can get the FieldResult
dateField->Update();
// Display some information from this field
// The field result is where the last evaluated value is stored. This is what is displayed in the document
// When field codes are not showing
ASSERT_EQ(System::DateTime::get_Today(), System::DateTime::Parse(dateField->get_Result()));
// Display the field code which defines the behavior of the field. This can been seen in Microsoft Word by pressing ALT+F9
ASSERT_EQ(u"DATE \\* MERGEFORMAT", dateField->GetFieldCode());
// The field type defines what type of field in the Document this is. In this case the type is "FieldDate"
ASSERT_EQ(FieldType::FieldDate, dateField->get_Type());
// Finally let's completely remove the field from the document. This can easily be done by invoking the Remove method on the object
dateField->Remove();

#include <Aspose.Words.Cpp/Model/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< FieldEndget_End () const
 Gets the node that represents the field end. More...
 
SharedPtr< FieldEndget_FieldEnd () const
 Gets the node that represents the field end. More...
 
SharedPtr< FieldStartget_FieldStart () const
 Gets the node that represents the start of the field. More...
 
SharedPtr< FieldFormatget_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< FieldSeparatorget_Separator ()
 Gets the node that represents the field separator. Can be null. More...
 
SharedPtr< FieldStartget_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 TypeInfoGetType () const override
 
virtual bool Is (const TypeInfo &target) const override
 
SharedPtr< NodeRemove ()
 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...
 
- Public Member Functions inherited from Object
ASPOSECPP_SHARED_API Object ()
 
ASPOSECPP_SHARED_API Object (Object const &x)
 
virtual ASPOSECPP_SHARED_API ~Object ()
 
virtual ASPOSECPP_SHARED_API bool Equals (ptr obj)
 
Detail::SmartPtrCounter * GetCounter ()
 
virtual ASPOSECPP_SHARED_API int GetHashCode () const
 
ASPOSECPP_SHARED_API void Lock ()
 
virtual ASPOSECPP_SHARED_API ptr MemberwiseClone () const
 
Objectoperator= (Object const &x)
 
bool ReferenceEquals (String const &str, std::nullptr_t)
 
bool ReferenceEquals (String const &str1, String const &str2)
 
int RemovedSharedRefs (int count)
 
virtual ASPOSECPP_SHARED_API void SetTemplateWeakPtr (unsigned int argument)
 
int SharedCount () const
 
ObjectSharedRefAdded ()
 
int SharedRefRemovedSafe ()
 
virtual ASPOSECPP_SHARED_API String ToString () const
 
ASPOSECPP_SHARED_API void Unlock ()
 
Detail::SmartPtrCounter * WeakRefAdded ()
 
void WeakRefRemoved ()
 

Static Public Member Functions

static const TypeInfoType ()
 
- Static Public Member Functions inherited from Object
bool Equals (double const &objA, double const &objB)
 
bool Equals (float const &objA, float const &objB)
 
static std::enable_if<!IsSmartPtr< T1 >::value &&!IsSmartPtr< T2 >::value, bool >::type Equals (T1 const &objA, T2 const &objB)
 
static std::enable_if< IsSmartPtr< T1 >::value &&IsSmartPtr< T2 >::value, bool >::type Equals (T1 const &objA, T2 const &objB)
 
static bool ReferenceEquals (ptr const &objA, ptr const &objB)
 
static std::enable_if<!IsSmartPtr< T >::value, bool >::type ReferenceEquals (T const &objA, std::nullptr_t)
 
static std::enable_if<!IsSmartPtr< T >::value, bool >::type ReferenceEquals (T const &objA, T const &objB)
 
static const TypeInfoType ()
 

Additional Inherited Members

- Public Types inherited from Object
typedef SmartPtr< Objectptr
 
typedef System::Details::SharedMembersType shared_members_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 text that represents the displayed field result.

auto document = MakeObject<Document>(MyDir + u"Various fields.docx");
SharedPtr<FieldCollection> fields = document->get_Range()->get_Fields();
ASSERT_EQ(u"111", fields->idx_get(0)->get_DisplayResult());
ASSERT_EQ(u"222", fields->idx_get(1)->get_DisplayResult());
ASSERT_EQ(u"Multi\rLine\rText", fields->idx_get(2)->get_DisplayResult());
ASSERT_EQ(u"%", fields->idx_get(3)->get_DisplayResult());
ASSERT_EQ(u"Macro Button Text", fields->idx_get(4)->get_DisplayResult());
ASSERT_EQ(String::Empty, fields->idx_get(5)->get_DisplayResult());
// Method must be called to obtain correct value for the "FieldListNum", "FieldAutoNum",
// "FieldAutoNumOut" and "FieldAutoNumLgl" fields
document->UpdateListLabels();
ASSERT_EQ(u"1)", fields->idx_get(5)->get_DisplayResult());

◆ get_End()

System::SharedPtr<Aspose::Words::Fields::FieldEnd> Aspose::Words::Fields::Field::get_End ( ) const

Gets the node that represents the field end.

◆ get_FieldEnd()

System::SharedPtr<Aspose::Words::Fields::FieldEnd> Aspose::Words::Fields::Field::get_FieldEnd ( ) const

Gets the node that represents the field end.

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

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

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Use a document builder to insert field with no format
SharedPtr<Field> field = builder->InsertField(u"= 2 + 3");
// We can format our field here instead of in the field code
SharedPtr<FieldFormat> format = field->get_Format();
format->set_NumericFormat(u"$###.00");
field->Update();
ASSERT_EQ(u"$ 5.00", field->get_Result());
// Apply a date/time format
field = builder->InsertField(u"DATE");
format = field->get_Format();
format->set_DateTimeFormat(u"dddd, MMMM dd, yyyy");
field->Update();
System::Console::WriteLine(String::Format(u"Today's date, in {0} format:\n\t{1}", format->get_DateTimeFormat(), field->get_Result()));
// Apply 2 general formats at the same time
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())
{
System::Console::WriteLine(String::Format(u"General format index {0}: {1}", index++, generalFormatEnumerator->get_Current()));
}
}
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));
// Removing field formats
format->get_GeneralFormats()->Remove(GeneralFormat::LowercaseRoman);
format->get_GeneralFormats()->RemoveAt(0);
ASSERT_EQ(0, format->get_GeneralFormats()->get_Count());
field->Update();
// Our field has no general formats left and is back to default form
ASSERT_EQ(u"58", field->get_Result());

◆ 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 property "Author" a value and 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 "Author" property
doc->get_BuiltInDocumentProperties()->set_Author(u"John & Jane Doe");
// AUTHOR is one of the field types whose fields do not update according to their source values in real time,
// and need to be updated manually beforehand every time an accurate value is required
ASSERT_EQ(u"John Doe", field->get_Result());
// Since the field's value is out of date, we can mark it as "Dirty"
field->set_IsDirty(true);
{
auto docStream = MakeObject<System::IO::MemoryStream>();
doc->Save(docStream, SaveFormat::Docx);
// Re-open the document from the stream while using a LoadOptions object to specify
// whether to update all fields marked as "Dirty" in the process, so they can display accurate values immediately
auto options = MakeObject<LoadOptions>();
options->set_UpdateDirtyFields(doUpdateDirtyFields);
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));
if (doUpdateDirtyFields)
{
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

Demonstrates how to retrieve the field class from an existing FieldStart node in the document.

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());
// This updates only this field in the document
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 print the date it will display, formatted according to your thread's current culture
SharedPtr<Field> field = builder->InsertField(u"DATE");
System::Console::WriteLine(String::Format(u"Today's date, as displayed in the \"{0}\" culture: {1}", System::Globalization::CultureInfo::get_CurrentCulture()->get_EnglishName(), field->get_Result()));
ASSERT_EQ(1033, field->get_LocaleId());
// We can get the field to display a date in a different format if we change the current thread's culture
// If we want to avoid making such an all encompassing change,
// we can set this option to get the document's fields to get their culture from themselves
// Then, we can change a field's LocaleId and it will display its result in any culture we choose
doc->get_FieldOptions()->set_FieldUpdateCultureSource(FieldUpdateCultureSource::FieldCode);
auto de = MakeObject<System::Globalization::CultureInfo>(u"de-DE");
field->set_LocaleId(de->get_LCID());
field->Update();
System::Console::WriteLine(String::Format(u"Today's date, as displayed according to the \"{0}\" culture: {1}", System::Globalization::CultureInfo::GetCultureInfo(field->get_LocaleId())->get_EnglishName(), field->get_Result()));

◆ 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 by FieldCode.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Insert a simple Date field into the document
// When we insert a field through the DocumentBuilder class we can get the
// special Field object which contains information about the field
SharedPtr<Field> dateField = builder->InsertField(u"DATE \\* MERGEFORMAT");
// Update this particular field in the document so we can get the FieldResult
dateField->Update();
// Display some information from this field
// The field result is where the last evaluated value is stored. This is what is displayed in the document
// When field codes are not showing
ASSERT_EQ(System::DateTime::get_Today(), System::DateTime::Parse(dateField->get_Result()));
// Display the field code which defines the behavior of the field. This can been seen in Microsoft Word by pressing ALT+F9
ASSERT_EQ(u"DATE \\* MERGEFORMAT", dateField->GetFieldCode());
// The field type defines what type of field in the Document this is. In this case the type is "FieldDate"
ASSERT_EQ(FieldType::FieldDate, dateField->get_Type());
// Finally let's completely remove the field from the document. This can easily be done by invoking the Remove method on the object
dateField->Remove();

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

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

◆ 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 by FieldCode.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Insert a simple Date field into the document
// When we insert a field through the DocumentBuilder class we can get the
// special Field object which contains information about the field
SharedPtr<Field> dateField = builder->InsertField(u"DATE \\* MERGEFORMAT");
// Update this particular field in the document so we can get the FieldResult
dateField->Update();
// Display some information from this field
// The field result is where the last evaluated value is stored. This is what is displayed in the document
// When field codes are not showing
ASSERT_EQ(System::DateTime::get_Today(), System::DateTime::Parse(dateField->get_Result()));
// Display the field code which defines the behavior of the field. This can been seen in Microsoft Word by pressing ALT+F9
ASSERT_EQ(u"DATE \\* MERGEFORMAT", dateField->GetFieldCode());
// The field type defines what type of field in the Document this is. In this case the type is "FieldDate"
ASSERT_EQ(FieldType::FieldDate, dateField->get_Type());
// Finally let's completely remove the field from the document. This can easily be done by invoking the Remove method on the object
dateField->Remove();

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

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Insert a simple Date field into the document
// When we insert a field through the DocumentBuilder class we can get the
// special Field object which contains information about the field
SharedPtr<Field> dateField = builder->InsertField(u"DATE \\* MERGEFORMAT");
// Update this particular field in the document so we can get the FieldResult
dateField->Update();
// Display some information from this field
// The field result is where the last evaluated value is stored. This is what is displayed in the document
// When field codes are not showing
ASSERT_EQ(System::DateTime::get_Today(), System::DateTime::Parse(dateField->get_Result()));
// Display the field code which defines the behavior of the field. This can been seen in Microsoft Word by pressing ALT+F9
ASSERT_EQ(u"DATE \\* MERGEFORMAT", dateField->GetFieldCode());
// The field type defines what type of field in the Document this is. In this case the type is "FieldDate"
ASSERT_EQ(FieldType::FieldDate, dateField->get_Type());
// Finally let's completely remove the field from the document. This can easily be done by invoking the Remove method on the object
dateField->Remove();

Shows how to get text between field start and field separator (or field end if there is no separator).

// Open a document which contains a MERGEFIELD inside an IF field
auto doc = MakeObject<Document>(MyDir + u"Nested fields.docx");
// Get the outer IF field and print its full field code
auto fieldIf = System::DynamicCast<FieldIf>(doc->get_Range()->get_Fields()->idx_get(0));
System::Console::WriteLine(String::Format(u"Full field code including child fields:\n\t{0}", fieldIf->GetFieldCode()));
// All inner nested fields are printed by default
ASSERT_EQ(fieldIf->GetFieldCode(), fieldIf->GetFieldCode(true));
// Print the field code again but this time without the inner MERGEFIELD
System::Console::WriteLine(String::Format(u"Field code with nested fields omitted:\n\t{0}", fieldIf->GetFieldCode(false)));

◆ 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
includeChildFieldCodesTrue if child field codes should be included.
Examples

Shows how to get text between field start and field separator (or field end if there is no separator).

// Open a document which contains a MERGEFIELD inside an IF field
auto doc = MakeObject<Document>(MyDir + u"Nested fields.docx");
// Get the outer IF field and print its full field code
auto fieldIf = System::DynamicCast<FieldIf>(doc->get_Range()->get_Fields()->idx_get(0));
System::Console::WriteLine(String::Format(u"Full field code including child fields:\n\t{0}", fieldIf->GetFieldCode()));
// All inner nested fields are printed by default
ASSERT_EQ(fieldIf->GetFieldCode(), fieldIf->GetFieldCode(true));
// Print the field code again but this time without the inner MERGEFIELD
System::Console::WriteLine(String::Format(u"Field code with nested fields omitted:\n\t{0}", fieldIf->GetFieldCode(false)));

◆ GetType()

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

Reimplemented from System::Object.

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

◆ Is()

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

Reimplemented from System::Object.

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

◆ 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 insert a field into a document by FieldCode.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Insert a simple Date field into the document
// When we insert a field through the DocumentBuilder class we can get the
// special Field object which contains information about the field
SharedPtr<Field> dateField = builder->InsertField(u"DATE \\* MERGEFORMAT");
// Update this particular field in the document so we can get the FieldResult
dateField->Update();
// Display some information from this field
// The field result is where the last evaluated value is stored. This is what is displayed in the document
// When field codes are not showing
ASSERT_EQ(System::DateTime::get_Today(), System::DateTime::Parse(dateField->get_Result()));
// Display the field code which defines the behavior of the field. This can been seen in Microsoft Word by pressing ALT+F9
ASSERT_EQ(u"DATE \\* MERGEFORMAT", dateField->GetFieldCode());
// The field type defines what type of field in the Document this is. In this case the type is "FieldDate"
ASSERT_EQ(FieldType::FieldDate, dateField->get_Type());
// Finally let's completely remove the field from the document. This can easily be done by invoking the Remove method on the object
dateField->Remove();

◆ set_IsDirty()

void Aspose::Words::Fields::Field::set_IsDirty ( bool  value)

◆ set_IsLocked()

void Aspose::Words::Fields::Field::set_IsLocked ( bool  value)

◆ set_LocaleId()

void Aspose::Words::Fields::Field::set_LocaleId ( int32_t  value)

◆ set_Result()

void Aspose::Words::Fields::Field::set_Result ( System::String  value)

◆ 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 specific 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 by FieldCode.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Insert a simple Date field into the document
// When we insert a field through the DocumentBuilder class we can get the
// special Field object which contains information about the field
SharedPtr<Field> dateField = builder->InsertField(u"DATE \\* MERGEFORMAT");
// Update this particular field in the document so we can get the FieldResult
dateField->Update();
// Display some information from this field
// The field result is where the last evaluated value is stored. This is what is displayed in the document
// When field codes are not showing
ASSERT_EQ(System::DateTime::get_Today(), System::DateTime::Parse(dateField->get_Result()));
// Display the field code which defines the behavior of the field. This can been seen in Microsoft Word by pressing ALT+F9
ASSERT_EQ(u"DATE \\* MERGEFORMAT", dateField->GetFieldCode());
// The field type defines what type of field in the Document this is. In this case the type is "FieldDate"
ASSERT_EQ(FieldType::FieldDate, dateField->get_Type());
// Finally let's completely remove the field from the document. This can easily be done by invoking the Remove method on the object
dateField->Remove();

◆ Update() [2/2]

void Aspose::Words::Fields::Field::Update ( bool  ignoreMergeFormat)

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

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

Shows a way to update a field ignoring the MERGEFORMAT switch.

auto loadOptions = MakeObject<LoadOptions>();
loadOptions->set_PreserveIncludePictureField(true);
auto doc = MakeObject<Document>(MyDir + u"Field sample - INCLUDEPICTURE.docx", loadOptions);
auto includePicture = System::DynamicCast<FieldIncludePicture>(doc->get_Range()->get_Fields()->LINQ_First([](SharedPtr<Field> f) { return f->get_Type() == FieldType::FieldIncludePicture; }));
includePicture->set_SourceFullName(ImageDir + u"Transparent background logo.png");
includePicture->Update(true);
doc->UpdateFields();
doc->Save(ArtifactsDir + u"Field.UpdateFieldIgnoringMergeFormat.docx");
@ Upper
Text formatting. All letters are uppercase.
static ASPOSECPP_SHARED_API DateTime Parse(const String &s)
static ASPOSECPP_SHARED_API void WriteLine()
@ Docx
Saves the document as an Office Open XML WordprocessingML Document (macro-free).
@ FieldCode
The culture specified in the field formatting properties via language setting is used.
@ LowercaseRoman
Numeric formatting. Lowercase Roman (i, ii, iii, ...).
static ASPOSECPP_SHARED_API CultureInfoPtr GetCultureInfo(const String &name)
static ASPOSECPP_SHARED_API const CultureInfoPtr & get_CurrentCulture()
@ FieldAuthor
Specifies the AUTHOR field.
@ FieldDate
Specifies the DATE field.
static ASPOSECPP_SHARED_API DateTime get_Today()