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

Represents a Microsoft Word document field. More...

#include "Aspose.Words.Cpp/Model/Fields/Field.h"

Inherits System::Object.

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

Public Member Functions

System::SharedPtr< Aspose::Words::Fields::FieldStartget_FieldStart () const
 Gets the node that represents the start of the field. More...
 
System::SharedPtr< Aspose::Words::Fields::FieldSeparatorget_Separator ()
 Gets the node that represents the field separator. Can be null. More...
 
System::SharedPtr< Aspose::Words::Fields::FieldEndget_FieldEnd () const
 Gets the node that represents the field end. More...
 
virtual Aspose::Words::Fields::FieldType get_Type ()
 Gets the Microsoft Word field type. More...
 
System::String get_Result ()
 Gets or sets text that is between the field separator and field end. More...
 
void set_Result (System::String value)
 Setter for Aspose::Words::Fields::Field::get_Result. More...
 
System::String get_DisplayResult ()
 Gets the text that represents the displayed field result. More...
 
bool get_IsLocked ()
 Gets or sets whether the field is locked (should not recalculate its result). More...
 
void set_IsLocked (bool value)
 Setter for Aspose::Words::Fields::Field::get_IsLocked. 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...
 
void set_IsDirty (bool value)
 Setter for Aspose::Words::Fields::Field::get_IsDirty. More...
 
System::SharedPtr< Aspose::Words::Fields::FieldFormatget_Format ()
 Gets a Aspose::Words::Fields::FieldFormat object that provides typed access to field's formatting. More...
 
int32_t get_LocaleId ()
 Gets or sets the LCID of the field. More...
 
void set_LocaleId (int32_t value)
 Setter for Aspose::Words::Fields::Field::get_LocaleId. More...
 
System::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...
 
System::String GetFieldCode (bool includeChildFieldCodes)
 Returns text between field start and field separator (or field end if there is no separator). More...
 
System::SharedPtr< Aspose::Words::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 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...
 
bool Unlink ()
 Performs the field unlink. More...
 
- Public Member Functions inherited from System::Object
 Object ()
 Creates object. Initializes all internal data structures. More...
 
virtual ~Object ()
 Destroys object. Frees all internal data structures. More...
 
 Object (Object const &x)
 Copy constructor. Doesn't copy anything, really, just initializes new object and enables copy constructing subclasses. More...
 
Objectoperator= (Object const &x)
 Assignment operator. Doesn't copy anything, really, just initializes new object and enables copy constructing subclasses. More...
 
ObjectSharedRefAdded ()
 Increments shared reference count. Shouldn't be called directly; instead, use smart pointers or ThisProtector. More...
 
int SharedRefRemovedSafe ()
 Decrements and returns shared reference count. Shouldn't be called directly; instead, use smart pointers or ThisProtector. More...
 
int RemovedSharedRefs (int count)
 Decreases shared reference count by specified value. More...
 
Detail::SmartPtrCounter * WeakRefAdded ()
 Increments weak reference count. Shouldn't be called directly; instead, use smart pointers or ThisProtector. More...
 
void WeakRefRemoved ()
 Decrements weak reference count. Shouldn't be called directly; instead, use smart pointers or ThisProtector. More...
 
Detail::SmartPtrCounter * GetCounter ()
 Gets reference counter data structure associated with the object. More...
 
int SharedCount () const
 Gets current value of shared refernce counter. More...
 
void Lock ()
 Implements C# lock() statement locking. Call directly or use LockContext sentry object. More...
 
void Unlock ()
 Implements C# lock() statement unlocking. Call directly or use LockContext sentry object. More...
 
virtual bool Equals (ptr obj)
 Compares objects using C# Object.Equals semantics. More...
 
virtual int GetHashCode () const
 Analog of C# Object.GetHashCode() method. Enables hashing of custom objects. More...
 
virtual String ToString () ASPOSE_CONST
 Analog of C# Object.ToString() method. Enables converting custom objects to string. More...
 
virtual ptr MemberwiseClone () const
 Analog of C# Object.MemberwiseClone() method. Enables cloning custom types. More...
 
virtual const TypeInfoGetType () const
 Gets actual type of object. Analog of C# System.Object.GetType() call. More...
 
virtual bool Is (const TypeInfo &targetType) const
 Check if object represents an instance of type described by targetType. Analog of C# 'is' operator. More...
 
virtual void SetTemplateWeakPtr (unsigned int argument)
 Set n'th template argument a weak pointer (rather than shared). Allows switching pointers in containers to weak mode. More...
 

Additional Inherited Members

- Public Types inherited from System::Object
typedef SmartPtr< Objectptr
 Alias for smart pointer type. More...
 
typedef System::Details::SharedMembersType shared_members_type
 structure to keep list of shared pointers contained in object. More...
 
- Static Public Member Functions inherited from System::Object
static bool ReferenceEquals (ptr const &objA, ptr const &objB)
 Compares objects by reference. More...
 
template<typename T >
static std::enable_if<!IsSmartPtr< T >::value, bool >::type ReferenceEquals (T const &objA, T const &objB)
 Compares objects by reference. More...
 
template<typename T >
static std::enable_if<!IsSmartPtr< T >::value, bool >::type ReferenceEquals (T const &objA, std::nullptr_t)
 Reference-compares value type object with nullptr. More...
 
template<typename T1 , typename T2 >
static std::enable_if< IsSmartPtr< T1 >::value &&IsSmartPtr< T2 >::value, bool >::type Equals (T1 const &objA, T2 const &objB)
 Compares reference type objects in C# style. More...
 
template<typename T1 , typename T2 >
static std::enable_if<!IsSmartPtr< T1 >::value &&!IsSmartPtr< T2 >::value, bool >::type Equals (T1 const &objA, T2 const &objB)
 Compares value type objects in C# style. More...
 
static const TypeInfoType ()
 Impleemnts C# typeof(System.Object) construct. More...
 
template<>
bool Equals (float const &objA, float const &objB)
 
template<>
bool Equals (double const &objA, double const &objB)
 
template<>
bool ReferenceEquals (String const &str, std::nullptr_t)
 
template<>
bool ReferenceEquals (String const &str1, String const &str2)
 

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 Aspose::Words::Fields::Field class is a "facade" object that provides properties and methods that allow to work with a field as a single object.

The Aspose::Words::Fields::Field::get_Start, Aspose::Words::Fields::Field::get_Separator and Aspose::Words::Fields::Field::get_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 Aspose::Words::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 Aspose::Words::Fields::Field::Update method. To update fields in the whole document use Aspose::Words::Document::UpdateFields.

You can get the plain text version of the field code using the Aspose::Words::Fields::Field::GetFieldCode(bool) method. You can get and set the plain text version of the field result using the Aspose::Words::Fields::Field::get_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 Aspose::Words::Fields::Field class directly. To create a new field use the Aspose::Words::DocumentBuilder::InsertField(System::String) method.

Member Function Documentation

◆ get_DisplayResult()

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

Gets the text that represents the displayed field result.

The Aspose::Words::Document::UpdateListLabels method must be called to obtain correct value for the Aspose::Words::Fields::FieldListNum, Aspose::Words::Fields::FieldAutoNum, Aspose::Words::Fields::FieldAutoNumOut and Aspose::Words::Fields::FieldAutoNumLgl fields.

◆ 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 Aspose::Words::Fields::FieldFormat object that provides typed access to field's formatting.

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

◆ get_IsLocked()

bool Aspose::Words::Fields::Field::get_IsLocked ( )

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

◆ 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

◆ get_Result()

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

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

◆ 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_Type()

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

Gets the Microsoft Word field type.

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.

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

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

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

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

◆ Update() [1/2]

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

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

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