Represents a start of a Word field in a document.

FieldStart is an inline-level node and represented by the FieldStartChar control character in the document.

FieldStart can only be a child of Paragraph.

A complete field in a Microsoft Word document is a complex structure consisting of a field start character, field code, field separator character, field result and field end character. Some fields only have field start, field code and field end.

To easily insert a new field into a document, use the InsertField() method.

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;
};

Shows how to find all hyperlinks in a Word document, and then change their URLs and display names.

#include <cstdint>
#include <Aspose.Words.Cpp/CompositeNode.h>
#include <Aspose.Words.Cpp/Document.h>
#include <Aspose.Words.Cpp/Fields/FieldStart.h>
#include <Aspose.Words.Cpp/Fields/FieldType.h>
#include <Aspose.Words.Cpp/Node.h>
#include <Aspose.Words.Cpp/NodeList.h>
#include <Aspose.Words.Cpp/NodeType.h>
#include <Aspose.Words.Cpp/Run.h>
#include <Aspose.Words.Cpp/Saving/SaveOutputParameters.h>
#include <system/collections/ienumerable.h>
#include <system/enumerator_adapter.h>
#include <system/exceptions.h>
#include <system/linq/enumerable.h>
#include <system/object_ext.h>
#include <system/text/regularexpressions/group.h>
#include <system/text/regularexpressions/group_collection.h>
#include <system/text/regularexpressions/match.h>
#include <system/text/regularexpressions/regex.h>
#include <system/text/string_builder.h>
 
#include "ApiExampleBase.h"
 
using System::ArrayPtr;
using System::MakeArray;
using System::MakeObject;
using System::SharedPtr;
using System::String;
 
using namespace Aspose::Words;
using namespace Aspose::Words::Fields;
 
namespace ApiExamples {
 
class Hyperlink : public System::Object
{
public:
    String get_Name()
    {
        return GetTextSameParent(mFieldSeparator, mFieldEnd);
    }
 
    void set_Name(String value)
    {
        // Hyperlink display name is stored in the field result, which is a Run
        // node between field separator and field end.
        auto fieldResult = System::DynamicCast<Run>(mFieldSeparator->get_NextSibling());
        fieldResult->set_Text(value);
 
        // If the field result consists of more than one run, delete these runs.
        RemoveSameParent(fieldResult->get_NextSibling(), mFieldEnd);
    }
 
    String get_Target()
    {
        return mTarget;
    }
 
    void set_Target(String value)
    {
        mTarget = value;
        UpdateFieldCode();
    }
 
    bool get_IsLocal()
    {
        return mIsLocal;
    }
 
    void set_IsLocal(bool value)
    {
        mIsLocal = value;
        UpdateFieldCode();
    }
 
    Hyperlink(SharedPtr<FieldStart> fieldStart) : mIsLocal(false)
    {
        if (fieldStart == nullptr)
        {
            throw System::ArgumentNullException(u"fieldStart");
        }
        if (fieldStart->get_FieldType() != FieldType::FieldHyperlink)
        {
            throw System::ArgumentException(u"Field start type must be FieldHyperlink.");
        }
 
        mFieldStart = fieldStart;
 
        // Find the field separator node.
        mFieldSeparator = FindNextSibling(mFieldStart, NodeType::FieldSeparator);
        if (mFieldSeparator == nullptr)
        {
            throw System::InvalidOperationException(u"Cannot find field separator.");
        }
 
        // Normally, we can always find the field's end node, but the example document
        // contains a paragraph break inside a hyperlink, which puts the field end
        // in the next paragraph. It will be much more complicated to handle fields which span several
        // paragraphs correctly. In this case allowing field end to be null is enough.
        mFieldEnd = FindNextSibling(mFieldSeparator, NodeType::FieldEnd);
 
        // Field code looks something like "HYPERLINK "http:\\www.myurl.com"", but it can consist of several runs.
        String fieldCode = GetTextSameParent(mFieldStart->get_NextSibling(), mFieldSeparator);
        SharedPtr<System::Text::RegularExpressions::Match> match = gRegex->Match(fieldCode.Trim());
 
        // The hyperlink is local if \l is present in the field code.
        mIsLocal = match->get_Groups()->idx_get(1)->get_Length() > 0;
        mTarget = match->get_Groups()->idx_get(2)->get_Value();
    }
 
private:
    SharedPtr<Node> mFieldStart;
    SharedPtr<Node> mFieldSeparator;
    SharedPtr<Node> mFieldEnd;
    bool mIsLocal;
    String mTarget;
    static SharedPtr<System::Text::RegularExpressions::Regex> gRegex;
 
    void UpdateFieldCode()
    {
        // A field's field code is in a Run node between the field's start node and field separator.
        auto fieldCode = System::DynamicCast<Run>(mFieldStart->get_NextSibling());
        fieldCode->set_Text(String::Format(u"HYPERLINK {0}\"{1}\"", ((mIsLocal) ? String(u"\\l ") : String(u"")), mTarget));
 
        // If the field code consists of more than one run, delete these runs.
        RemoveSameParent(fieldCode->get_NextSibling(), mFieldSeparator);
    }
 
    static SharedPtr<Node> FindNextSibling(SharedPtr<Node> startNode, NodeType nodeType)
    {
        for (SharedPtr<Node> node = startNode; node != nullptr; node = node->get_NextSibling())
        {
            if (node->get_NodeType() == nodeType)
            {
                return node;
            }
        }
 
        return nullptr;
    }
 
    static String GetTextSameParent(SharedPtr<Node> startNode, SharedPtr<Node> endNode)
    {
        if ((endNode != nullptr) && (startNode->get_ParentNode() != endNode->get_ParentNode()))
        {
            throw System::ArgumentException(u"Start and end nodes are expected to have the same parent.");
        }
 
        auto builder = MakeObject<System::Text::StringBuilder>();
        for (SharedPtr<Node> child = startNode; !System::ObjectExt::Equals(child, endNode); child = child->get_NextSibling())
        {
            builder->Append(child->GetText());
        }
 
        return builder->ToString();
    }
 
    static void RemoveSameParent(SharedPtr<Node> startNode, SharedPtr<Node> endNode)
    {
        if (endNode != nullptr && startNode->get_ParentNode() != endNode->get_ParentNode())
        {
            throw System::ArgumentException(u"Start and end nodes are expected to have the same parent.");
        }
 
        SharedPtr<Node> curChild = startNode;
        while ((curChild != nullptr) && (curChild != endNode))
        {
            SharedPtr<Node> nextChild = curChild->get_NextSibling();
            curChild->Remove();
            curChild = nextChild;
        }
    }
};
 
class ExReplaceHyperlinks : public ApiExampleBase
 
public:
    void Fields()
    {
        auto doc = MakeObject<Document>(MyDir + u"Hyperlinks.docx");
 
        // Hyperlinks in a Word documents are fields. To begin looking for hyperlinks, we must first find all the fields.
        // Use the "SelectNodes" method to find all the fields in the document via an XPath.
        SharedPtr<NodeList> fieldStarts = doc->SelectNodes(u"//FieldStart");
 
        for (const auto& fieldStart : System::IterateOver(fieldStarts->LINQ_OfType<SharedPtr<FieldStart>>()))
        {
            if (fieldStart->get_FieldType() == FieldType::FieldHyperlink)
            {
                auto hyperlink = MakeObject<Hyperlink>(fieldStart);
 
                // Hyperlinks that link to bookmarks do not have URLs.
                if (hyperlink->get_IsLocal())
                {
                    continue;
                }
 
                // Give each URL hyperlink a new URL and name.
                hyperlink->set_Target(NewUrl);
                hyperlink->set_Name(NewName);
            }
        }
 
        doc->Save(ArtifactsDir + u"ReplaceHyperlinks.Fields.docx");
    }
 
    static const String NewUrl;
    static const String NewName;
};
 
} // namespace ApiExamples

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

Inheritance diagram for Aspose::Words::Fields::FieldStart:

Public Member Functions
bool	Accept (SharedPtr< DocumentVisitor > visitor) override
	Accepts a visitor. More...

NodeType	get_NodeType () const override
	Returns FieldStart. More...

virtual const TypeInfo &	GetType () const override

virtual bool	Is (const TypeInfo &target) const override

Public Member Functions inherited from FieldChar
FieldType	get_FieldType () const
	Returns the type of the field. More...

bool	get_IsDirty () const
	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 () const
	Gets or sets whether the parent field is locked (should not recalculate its result). More...

SharedPtr< Field >	GetField ()
	Returns a field for the field char. More...

void	set_IsDirty (bool value)
	Setter for get_IsDirty. More...

void	set_IsLocked (bool value)
	Setter for get_IsLocked. More...

Public Member Functions inherited from SpecialChar
bool	Accept (SharedPtr< DocumentVisitor > visitor) override
	Accepts a visitor. More...

NodeType	get_NodeType () const override
	Returns NodeType.SpecialChar. More...

String	GetText () override
	Gets the special character that this node represents. More...

Public Member Functions inherited from Inline
SharedPtr< Font >	get_Font ()
	Provides access to the font formatting of this object. More...

bool	get_IsDeleteRevision ()
	Returns true if this object was deleted in Microsoft Word while change tracking was enabled. More...

bool	get_IsFormatRevision ()
	Returns true if formatting of the object was changed in Microsoft Word while change tracking was enabled. More...

bool	get_IsInsertRevision ()
	Returns true if this object was inserted in Microsoft Word while change tracking was enabled. More...

bool	get_IsMoveFromRevision ()
	Returns true if this object was moved (deleted) in Microsoft Word while change tracking was enabled. More...

bool	get_IsMoveToRevision ()
	Returns true if this object was moved (inserted) in Microsoft Word while change tracking was enabled. More...

SharedPtr< Paragraph >	get_ParentParagraph ()
	Retrieves the parent Paragraph of this node. More...

void	RemoveMoveRevisions () override

Public Member Functions inherited from Node
SharedPtr< Node >	Clone (bool isCloneChildren)
	Creates a duplicate of the node. More...

int32_t	get_CustomNodeId () const
	Specifies custom node identifier. More...

virtual SharedPtr< DocumentBase >	get_Document () const
	Gets the document to which this node belongs. More...

virtual bool	get_IsComposite ()
	Returns true if this node can contain other nodes. More...

SharedPtr< Node >	get_NextSibling ()
	Gets the node immediately following this node. More...

SharedPtr< CompositeNode >	get_ParentNode ()
	Gets the immediate parent of this node. More...

SharedPtr< Node >	get_PreviousSibling ()
	Gets the node immediately preceding this node. More...

SharedPtr< Range >	get_Range ()
	Returns a Range object that represents the portion of a document that is contained in this node. More...

SharedPtr< CompositeNode >	GetAncestor (NodeType ancestorType)
	Gets the first ancestor of the specified NodeType. More...

template<typename T >
T	GetAncestorOf ()

SharedPtr< Node >	NextPreOrder (SharedPtr< Node > rootNode)
	Gets next node according to the pre-order tree traversal algorithm. More...

SharedPtr< Node >	PreviousPreOrder (SharedPtr< Node > rootNode)
	Gets the previous node according to the pre-order tree traversal algorithm. More...

void	Remove ()
	Removes itself from the parent. More...

void	set_CustomNodeId (int32_t value)
	Setter for get_CustomNodeId. More...

String	ToString (SaveFormat saveFormat)
	Exports the content of the node into a string in the specified format. More...

String	ToString (SharedPtr< SaveOptions > saveOptions)
	Exports the content of the node into a string using the specified save options. More...

Static Public Member Functions
static const TypeInfo &	Type ()

Static Public Member Functions inherited from FieldChar
static const TypeInfo &	Type ()

Static Public Member Functions inherited from SpecialChar
static const TypeInfo &	Type ()

Static Public Member Functions inherited from Inline
static const TypeInfo &	Type ()

Static Public Member Functions inherited from Node
static String	NodeTypeToString (NodeType nodeType)
	A utility method that converts a node type enum value into a user friendly string. More...

static const TypeInfo &	Type ()

Member Function Documentation

◆ Accept()

bool Aspose::Words::Fields::FieldStart::Accept ( System::SharedPtr< Aspose::Words::DocumentVisitor > visitor )

overridevirtual

Accepts a visitor.

Calls VisitFieldStart().

For more info see the Visitor design pattern.

Parameters

visitor The visitor that will visit the node.

Returns: False if the visitor requested the enumeration to stop.

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;
};

Implements Aspose::Words::Node.

◆ get_NodeType()

Aspose::Words::NodeType Aspose::Words::Fields::FieldStart::get_NodeType ( ) const

overridevirtual

Returns FieldStart.

Examples

Shows how to traverse a composite node's tree of child nodes.

void RecurseChildren()
{
    auto doc = MakeObject<Document>(MyDir + u"Paragraphs.docx");
 
    // Any node that can contain child nodes, such as the document itself, is composite.
    ASSERT_TRUE(doc->get_IsComposite());
 
    // Invoke the recursive function that will go through and print all the child nodes of a composite node.
    TraverseAllNodes(doc, 0);
}
 
void TraverseAllNodes(SharedPtr<CompositeNode> parentNode, int depth)
{
    for (SharedPtr<Node> childNode = parentNode->get_FirstChild(); childNode != nullptr; childNode = childNode->get_NextSibling())
    {
        std::cout << (String(u'\t', depth)) << Node::NodeTypeToString(childNode->get_NodeType());
 
        // Recurse into the node if it is a composite node. Otherwise, print its contents if it is an inline node.
        if (childNode->get_IsComposite())
        {
            std::cout << std::endl;
            TraverseAllNodes(System::DynamicCast<CompositeNode>(childNode), depth + 1);
        }
        else if (System::ObjectExt::Is<Inline>(childNode))
        {
            std::cout << " - \"" << childNode->GetText().Trim() << "\"" << std::endl;
        }
        else
        {
            std::cout << std::endl;
        }
    }
}