Detailed Description

Represents a run of characters with the same font formatting.

All text of the document is stored in runs of text.

Run can only be a child of Paragraph or inline StructuredDocumentTag.

Examples

Shows how to format a run of text using its font property.

auto doc = MakeObject<Document>();
auto run = MakeObject<Run>(doc, u"Hello world!");
SharedPtr<Aspose::Words::Font> font = run->get_Font();
font->set_Name(u"Courier New");
font->set_Size(36);
font->set_HighlightColor(System::Drawing::Color::get_Yellow());
doc->get_FirstSection()->get_Body()->get_FirstParagraph()->AppendChild(run);
doc->Save(ArtifactsDir + u"Font.CreateFormattedRun.docx");

Shows how to add, update and delete child nodes in a CompositeNode's collection of children.

auto doc = MakeObject<Document>();
// An empty document, by default, has one paragraph.
ASSERT_EQ(1, doc->get_FirstSection()->get_Body()->get_Paragraphs()->get_Count());
// Composite nodes such as our paragraph can contain other composite and inline nodes as children.
SharedPtr<Paragraph> paragraph = doc->get_FirstSection()->get_Body()->get_FirstParagraph();
auto paragraphText = MakeObject<Run>(doc, u"Initial text. ");
paragraph->AppendChild(paragraphText);
// Create three more run nodes.
auto run1 = MakeObject<Run>(doc, u"Run 1. ");
auto run2 = MakeObject<Run>(doc, u"Run 2. ");
auto run3 = MakeObject<Run>(doc, u"Run 3. ");
// The document body will not display these runs until we insert them into a composite node
// that itself is a part of the document's node tree, as we did with the first run.
// We can determine where the text contents of nodes that we insert
// appears in the document by specifying an insertion location relative to another node in the paragraph.
ASSERT_EQ(u"Initial text.", paragraph->GetText().Trim());
// Insert the second run into the paragraph in front of the initial run.
paragraph->InsertBefore(run2, paragraphText);
ASSERT_EQ(u"Run 2. Initial text.", paragraph->GetText().Trim());
// Insert the third run after the initial run.
paragraph->InsertAfter(run3, paragraphText);
ASSERT_EQ(u"Run 2. Initial text. Run 3.", paragraph->GetText().Trim());
// Insert the first run to the start of the paragraph's child nodes collection.
paragraph->PrependChild(run1);
ASSERT_EQ(u"Run 1. Run 2. Initial text. Run 3.", paragraph->GetText().Trim());
ASSERT_EQ(4, paragraph->GetChildNodes(NodeType::Any, true)->get_Count());
// We can modify the contents of the run by editing and deleting existing child nodes.
(System::DynamicCast<Run>(paragraph->GetChildNodes(NodeType::Run, true)->idx_get(1)))->set_Text(u"Updated run 2. ");
paragraph->GetChildNodes(NodeType::Run, true)->Remove(paragraphText);
ASSERT_EQ(u"Run 1. Updated run 2. Run 3.", paragraph->GetText().Trim());
ASSERT_EQ(3, paragraph->GetChildNodes(NodeType::Any, true)->get_Count());

Shows how to construct an Aspose.Words document by hand.

auto doc = MakeObject<Document>();
// A blank document contains one section, one body and one paragraph.
// Call the "RemoveAllChildren" method to remove all those nodes,
// and end up with a document node with no children.
doc->RemoveAllChildren();
// This document now has no composite child nodes that we can add content to.
// If we wish to edit it, we will need to repopulate its node collection.
// First, create a new section, and then append it as a child to the root document node.
auto section = MakeObject<Section>(doc);
doc->AppendChild(section);
// Set some page setup properties for the section.
section->get_PageSetup()->set_SectionStart(SectionStart::NewPage);
section->get_PageSetup()->set_PaperSize(PaperSize::Letter);
// A section needs a body, which will contain and display all its contents
// on the page between the section's header and footer.
auto body = MakeObject<Body>(doc);
section->AppendChild(body);
// Create a paragraph, set some formatting properties, and then append it as a child to the body.
auto para = MakeObject<Paragraph>(doc);
para->get_ParagraphFormat()->set_StyleName(u"Heading 1");
para->get_ParagraphFormat()->set_Alignment(ParagraphAlignment::Center);
body->AppendChild(para);
// Finally, add some content to do the document. Create a run,
// set its appearance and contents, and then append it as a child to the paragraph.
auto run = MakeObject<Run>(doc);
run->set_Text(u"Hello World!");
run->get_Font()->set_Color(System::Drawing::Color::get_Red());
para->AppendChild(run);
ASSERT_EQ(u"Hello World!", doc->GetText().Trim());
doc->Save(ArtifactsDir + u"Section.CreateManually.docx");

#include <Aspose.Words.Cpp/Run.h>

+ Inheritance diagram for Aspose::Words::Run:

Public Member Functions

 Run (const SharedPtr< DocumentBase > &doc)
 Initializes a new instance of the Run class. More...
 
 Run (const SharedPtr< DocumentBase > &doc, const String &text)
 Initializes a new instance of the Run class. More...
 
bool Accept (SharedPtr< DocumentVisitor > visitor) override
 Accepts a visitor. More...
 
NodeType get_NodeType () const override
 Returns NodeType.Run. More...
 
String get_Text () const
 Gets or sets the text of the run. More...
 
String GetText () override
 Gets the text of the run. More...
 
virtual const TypeInfoGetType () const override
 
virtual bool Is (const TypeInfo &target) const override
 
void set_Text (const String &value)
 Setter for get_Text. More...
 
- Public Member Functions inherited from Inline
SharedPtr< Fontget_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< Paragraphget_ParentParagraph ()
 Retrieves the parent Paragraph of this node. More...
 
virtual const TypeInfoGetType () 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< NodeClone (bool isCloneChildren)
 Creates a duplicate of the node. More...
 
int32_t get_CustomNodeId () const
 Specifies custom node identifier. More...
 
virtual SharedPtr< DocumentBaseget_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< Nodeget_NextSibling ()
 Gets the node immediately following this node. More...
 
virtual NodeType get_NodeType () const =0
 Gets the type of this node. More...
 
SharedPtr< CompositeNodeget_ParentNode ()
 Gets the immediate parent of this node. More...
 
SharedPtr< Nodeget_PreviousSibling ()
 Gets the node immediately preceding this node. More...
 
SharedPtr< Rangeget_Range ()
 Returns a Range object that represents the portion of a document that is contained in this node. More...
 
SharedPtr< CompositeNodeGetAncestor (NodeType ancestorType)
 Gets the first ancestor of the specified NodeType. More...
 
template<typename T >
GetAncestorOf ()
 
virtual String GetText ()
 Gets the text of this node and of all its children. More...
 
virtual const TypeInfoGetType () const override
 
virtual bool Is (const TypeInfo &target) const override
 
SharedPtr< NodeNextPreOrder (const SharedPtr< Node > &rootNode)
 Gets next node according to the pre-order tree traversal algorithm. More...
 
SharedPtr< NodePreviousPreOrder (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 TypeInfoType ()
 
- Static Public Member Functions inherited from Inline
static const TypeInfoType ()
 
- 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 TypeInfoType ()
 

Constructor & Destructor Documentation

◆ Run() [1/2]

Aspose::Words::Run::Run ( const System::SharedPtr< Aspose::Words::DocumentBase > &  doc)

Initializes a new instance of the Run class.

When Run is created, it belongs to the specified document, but is not yet part of the document and ParentNode is null.

To append Run to the document use InsertAfter or InsertBefore on the paragraph where you want the run inserted.

Parameters
docThe owner document.
Examples

Shows how to construct an Aspose.Words document by hand.

auto doc = MakeObject<Document>();
// A blank document contains one section, one body and one paragraph.
// Call the "RemoveAllChildren" method to remove all those nodes,
// and end up with a document node with no children.
doc->RemoveAllChildren();
// This document now has no composite child nodes that we can add content to.
// If we wish to edit it, we will need to repopulate its node collection.
// First, create a new section, and then append it as a child to the root document node.
auto section = MakeObject<Section>(doc);
doc->AppendChild(section);
// Set some page setup properties for the section.
section->get_PageSetup()->set_SectionStart(SectionStart::NewPage);
section->get_PageSetup()->set_PaperSize(PaperSize::Letter);
// A section needs a body, which will contain and display all its contents
// on the page between the section's header and footer.
auto body = MakeObject<Body>(doc);
section->AppendChild(body);
// Create a paragraph, set some formatting properties, and then append it as a child to the body.
auto para = MakeObject<Paragraph>(doc);
para->get_ParagraphFormat()->set_StyleName(u"Heading 1");
para->get_ParagraphFormat()->set_Alignment(ParagraphAlignment::Center);
body->AppendChild(para);
// Finally, add some content to do the document. Create a run,
// set its appearance and contents, and then append it as a child to the paragraph.
auto run = MakeObject<Run>(doc);
run->set_Text(u"Hello World!");
run->get_Font()->set_Color(System::Drawing::Color::get_Red());
para->AppendChild(run);
ASSERT_EQ(u"Hello World!", doc->GetText().Trim());
doc->Save(ArtifactsDir + u"Section.CreateManually.docx");

◆ Run() [2/2]

Aspose::Words::Run::Run ( const System::SharedPtr< Aspose::Words::DocumentBase > &  doc,
const System::String text 
)

Initializes a new instance of the Run class.

When Run is created, it belongs to the specified document, but is not yet part of the document and ParentNode is null.

To append Run to the document use InsertAfter or InsertBefore on the paragraph where you want the run inserted.

Parameters
docThe owner document.
textThe text of the run.
Examples

Shows how to format a run of text using its font property.

auto doc = MakeObject<Document>();
auto run = MakeObject<Run>(doc, u"Hello world!");
SharedPtr<Aspose::Words::Font> font = run->get_Font();
font->set_Name(u"Courier New");
font->set_Size(36);
font->set_HighlightColor(System::Drawing::Color::get_Yellow());
doc->get_FirstSection()->get_Body()->get_FirstParagraph()->AppendChild(run);
doc->Save(ArtifactsDir + u"Font.CreateFormattedRun.docx");

Member Function Documentation

◆ Accept()

bool Aspose::Words::Run::Accept ( System::SharedPtr< Aspose::Words::DocumentVisitor visitor)
overridevirtual

Accepts a visitor.

Calls DocumentVisitor.VisitRun.

For more info see the Visitor design pattern.

Parameters
visitorThe visitor that will visit the node.
Returns
False if the visitor requested the enumeration to stop.
Examples

Shows how to print the node structure of every header and footer in a document.

void HeaderFooterToText()
{
auto doc = MakeObject<Document>(MyDir + u"DocumentVisitor-compatible features.docx");
auto visitor = MakeObject<ExDocumentVisitor::HeaderFooterStructurePrinter>();
// When we get a composite node to accept a document visitor, the visitor visits the accepting node,
// and then traverses all the node's children in a depth-first manner.
// The visitor can read and modify each visited node.
doc->Accept(visitor);
std::cout << visitor->GetText() << std::endl;
// An alternative way of accessing a document's header/footers section-by-section is by accessing the collection.
ArrayPtr<SharedPtr<HeaderFooter>> headerFooters = doc->get_FirstSection()->get_HeadersFooters()->ToArray();
ASSERT_EQ(3, headerFooters->get_Length());
}
class HeaderFooterStructurePrinter : public DocumentVisitor
{
public:
HeaderFooterStructurePrinter() : mVisitorIsInsideHeaderFooter(false), mDocTraversalDepth(0)
{
mBuilder = MakeObject<System::Text::StringBuilder>();
mVisitorIsInsideHeaderFooter = false;
}
String GetText()
{
return mBuilder->ToString();
}
VisitorAction VisitRun(SharedPtr<Run> run) override
{
if (mVisitorIsInsideHeaderFooter)
{
IndentAndAppendLine(String(u"[Run] \"") + run->GetText() + u"\"");
}
}
VisitorAction VisitHeaderFooterStart(SharedPtr<HeaderFooter> headerFooter) override
{
IndentAndAppendLine(String(u"[HeaderFooter start] HeaderFooterType: ") + System::ObjectExt::ToString(headerFooter->get_HeaderFooterType()));
mDocTraversalDepth++;
mVisitorIsInsideHeaderFooter = true;
}
VisitorAction VisitHeaderFooterEnd(SharedPtr<HeaderFooter> headerFooter) override
{
mDocTraversalDepth--;
IndentAndAppendLine(u"[HeaderFooter end]");
mVisitorIsInsideHeaderFooter = false;
}
private:
bool mVisitorIsInsideHeaderFooter;
int mDocTraversalDepth;
SharedPtr<System::Text::StringBuilder> mBuilder;
void IndentAndAppendLine(String text)
{
for (int i = 0; i < mDocTraversalDepth; i++)
{
mBuilder->Append(u"| ");
}
mBuilder->AppendLine(text);
}
};

Implements Aspose::Words::Node.

◆ get_NodeType()

Aspose::Words::NodeType Aspose::Words::Run::get_NodeType ( ) const
overridevirtual

Returns NodeType.Run.

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.

◆ get_Text()

System::String Aspose::Words::Run::get_Text ( ) const

Gets or sets the text of the run.

Examples

Shows how to construct an Aspose.Words document by hand.

auto doc = MakeObject<Document>();
// A blank document contains one section, one body and one paragraph.
// Call the "RemoveAllChildren" method to remove all those nodes,
// and end up with a document node with no children.
doc->RemoveAllChildren();
// This document now has no composite child nodes that we can add content to.
// If we wish to edit it, we will need to repopulate its node collection.
// First, create a new section, and then append it as a child to the root document node.
auto section = MakeObject<Section>(doc);
doc->AppendChild(section);
// Set some page setup properties for the section.
section->get_PageSetup()->set_SectionStart(SectionStart::NewPage);
section->get_PageSetup()->set_PaperSize(PaperSize::Letter);
// A section needs a body, which will contain and display all its contents
// on the page between the section's header and footer.
auto body = MakeObject<Body>(doc);
section->AppendChild(body);
// Create a paragraph, set some formatting properties, and then append it as a child to the body.
auto para = MakeObject<Paragraph>(doc);
para->get_ParagraphFormat()->set_StyleName(u"Heading 1");
para->get_ParagraphFormat()->set_Alignment(ParagraphAlignment::Center);
body->AppendChild(para);
// Finally, add some content to do the document. Create a run,
// set its appearance and contents, and then append it as a child to the paragraph.
auto run = MakeObject<Run>(doc);
run->set_Text(u"Hello World!");
run->get_Font()->set_Color(System::Drawing::Color::get_Red());
para->AppendChild(run);
ASSERT_EQ(u"Hello World!", doc->GetText().Trim());
doc->Save(ArtifactsDir + u"Section.CreateManually.docx");

◆ GetText()

System::String Aspose::Words::Run::GetText ( )
overridevirtual

Gets the text of the run.

Returns
The text of the run.
Examples

Shows how to print the node structure of every header and footer in a document.

void HeaderFooterToText()
{
auto doc = MakeObject<Document>(MyDir + u"DocumentVisitor-compatible features.docx");
auto visitor = MakeObject<ExDocumentVisitor::HeaderFooterStructurePrinter>();
// When we get a composite node to accept a document visitor, the visitor visits the accepting node,
// and then traverses all the node's children in a depth-first manner.
// The visitor can read and modify each visited node.
doc->Accept(visitor);
std::cout << visitor->GetText() << std::endl;
// An alternative way of accessing a document's header/footers section-by-section is by accessing the collection.
ArrayPtr<SharedPtr<HeaderFooter>> headerFooters = doc->get_FirstSection()->get_HeadersFooters()->ToArray();
ASSERT_EQ(3, headerFooters->get_Length());
}
class HeaderFooterStructurePrinter : public DocumentVisitor
{
public:
HeaderFooterStructurePrinter() : mVisitorIsInsideHeaderFooter(false), mDocTraversalDepth(0)
{
mBuilder = MakeObject<System::Text::StringBuilder>();
mVisitorIsInsideHeaderFooter = false;
}
String GetText()
{
return mBuilder->ToString();
}
VisitorAction VisitRun(SharedPtr<Run> run) override
{
if (mVisitorIsInsideHeaderFooter)
{
IndentAndAppendLine(String(u"[Run] \"") + run->GetText() + u"\"");
}
}
VisitorAction VisitHeaderFooterStart(SharedPtr<HeaderFooter> headerFooter) override
{
IndentAndAppendLine(String(u"[HeaderFooter start] HeaderFooterType: ") + System::ObjectExt::ToString(headerFooter->get_HeaderFooterType()));
mDocTraversalDepth++;
mVisitorIsInsideHeaderFooter = true;
}
VisitorAction VisitHeaderFooterEnd(SharedPtr<HeaderFooter> headerFooter) override
{
mDocTraversalDepth--;
IndentAndAppendLine(u"[HeaderFooter end]");
mVisitorIsInsideHeaderFooter = false;
}
private:
bool mVisitorIsInsideHeaderFooter;
int mDocTraversalDepth;
SharedPtr<System::Text::StringBuilder> mBuilder;
void IndentAndAppendLine(String text)
{
for (int i = 0; i < mDocTraversalDepth; i++)
{
mBuilder->Append(u"| ");
}
mBuilder->AppendLine(text);
}
};

Reimplemented from Aspose::Words::Node.

◆ GetType()

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

Reimplemented from Aspose::Words::Inline.

◆ Is()

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

Reimplemented from Aspose::Words::Inline.

◆ set_Text()

void Aspose::Words::Run::set_Text ( const System::String value)

◆ Type()

static const System::TypeInfo & Aspose::Words::Run::Type ( )
static