Aspose::Words::Fields::FieldStart Class Reference

Detailed Description

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...
const ArrayPtr< uint8_t > &	get_FieldData () const
	Gets custom field data which is associated with the field. 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...
virtual const TypeInfo &	GetType () const override
virtual bool	Is (const TypeInfo &target) const override
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...
virtual const TypeInfo &	GetType () const override
virtual bool	Is (const TypeInfo &target) const override
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...
virtual const TypeInfo &	GetType () const override
virtual bool	Is (const TypeInfo &target) const override
Public Member Functions inherited from Node
virtual bool	Accept (SharedPtr< DocumentVisitor > visitor)=0
	Accepts a visitor. More...
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...
virtual NodeType	get_NodeType () const =0
	Gets the type of 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 ()
virtual String	GetText ()
	Gets the text of this node and of all its children. More...
virtual const TypeInfo &	GetType () const override
virtual bool	Is (const TypeInfo &target) const override
SharedPtr< Node >	NextPreOrder (const SharedPtr< Node > &rootNode)
	Gets next node according to the pre-order tree traversal algorithm. More...
SharedPtr< Node >	PreviousPreOrder (const 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 (const 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_FieldData()

const System::ArrayPtr< uint8_t > & Aspose::Words::Fields::FieldStart::get_FieldData

(

)

const

Gets custom field data which is associated with the field.

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

Implements Aspose::Words::Node.

GetType()

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

overridevirtual

Reimplemented from Aspose::Words::Fields::FieldChar.

Is()

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

overridevirtual

Reimplemented from Aspose::Words::Fields::FieldChar.

Type()

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

static