カーソルを使ったナビゲーション

文書を操作している間、それが短いものであっても長いものであっても、文書をナビゲートする必要があります。 仮想カーソルを使用したナビゲーションは、ドキュメント内の異なるノード間を移動する機能を表します。

短いドキュメント内では、キーボードの矢印キーを使用したり、マウスをクリックして任意の場所に挿入ポイントを移動したりすることで、ドキュメント内を移動するのは簡単です。 しかし、多くのページを持つ大規模な文書を作成すると、これらの基本的な手法は不十分になります。

この記事では、ドキュメント内を移動し、仮想カーソルを使用してドキュメントのさまざまな部分に移動する方法について説明します。

現在のカーソル位置の検出

ドキュメント内を移動するプロセスを開始する前に、現在選択されているノードを取得する必要があります。 CurrentNodeプロパティを使用すると、選択したノードでのカーソルの正確な位置を取得できます。 さらに、現在のノードを取得する代わりに、CurrentParagraphおよびCurrentSectionプロパティを使用して、現在選択されている段落または現在選択されているセクションを取得

DocumentBuilderを使用して実行する挿入操作は、CurrentNodeの前に挿入されます。 現在の段落が空の場合、またはカーソルが段落の終わりの直前に配置されている場合、CurrentNodeはnullptrを返します。

ドキュメント内のメソッドの移動

テキストを編集するときは、ドキュメントをナビゲートする方法と、ドキュメント内を正確に移動する場所を知っておくことが重要です。 これは、スクロールせずにWord文書内のページまたは見出しに移動するMicrosoft Wordのナビゲーションペインの機能に似ています。Aspose.Wordsは、ドキュメント内を移動して、その別のセクションやパーツに移動することができます。

主な方法は、カーソル位置をドキュメント内の特定のノードに移動できるようにすることです。MoveToメソッドを使用してこれを実現できます。

次のコード例は、DocumentBuilderをドキュメント内の別のノードに移動する方法を示しています:

For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-C
auto doc = System::MakeObject<Document>();
auto builder = System::MakeObject<DocumentBuilder>(doc);

// Start a bookmark and add content to it using a DocumentBuilder.
builder->StartBookmark(u"MyBookmark");
builder->Writeln(u"Bookmark contents.");
builder->EndBookmark(u"MyBookmark");

// The node that the DocumentBuilder is currently at is past the boundaries of the bookmark.
ASSERT_EQ(doc->get_Range()->get_Bookmarks()->idx_get(0)->get_BookmarkEnd(), builder->get_CurrentParagraph()->get_FirstChild());

// If we wish to revise the content of our bookmark with the DocumentBuilder, we can move back to it like this.
builder->MoveToBookmark(u"MyBookmark");

// Now we're located between the bookmark's BookmarkStart and BookmarkEnd nodes, so any text the builder adds will be within it.
ASSERT_EQ(doc->get_Range()->get_Bookmarks()->idx_get(0)->get_BookmarkStart(), builder->get_CurrentParagraph()->get_FirstChild());

// We can move the builder to an individual node,
// which in this case will be the first node of the first paragraph, like this.
builder->MoveTo(doc->get_FirstSection()->get_Body()->get_FirstParagraph()->GetChildNodes(NodeType::Any, false)->idx_get(0));

ASSERT_EQ(NodeType::BookmarkStart, builder->get_CurrentNode()->get_NodeType());
ASSERT_TRUE(builder->get_IsAtStartOfParagraph());

// A shorter way of moving the very start/end of a document is with these methods.
builder->MoveToDocumentEnd();
ASSERT_TRUE(builder->get_IsAtEndOfParagraph());
builder->MoveToDocumentStart();
ASSERT_TRUE(builder->get_IsAtStartOfParagraph());

しかし、基本的なMoveToメソッドのほかに、より具体的なものがあります。

ドキュメントの先頭または末尾に移動する

MoveToDocumentStartメソッドとMoveToDocumentEndメソッドを使用して、文書の先頭または末尾に移動できます。

次のコード例は、カーソル位置をドキュメントの先頭または末尾に移動する方法を示しています:

For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-C
auto doc = System::MakeObject<Document>(inputDataDir + u"Document.docx");
auto builder = System::MakeObject<DocumentBuilder>(doc);
// Move the cursor position to the beginning of your document.
builder->MoveToDocumentStart();
builder->Writeln(u"This is the beginning of the document.");

// Move the cursor position to the end of your document.
builder->MoveToDocumentEnd();
builder->Writeln(u"This is the end of the document.");

ブックマークでナビゲート

見つけたい場所に印を付けて、簡単に移動することができます。 必要な数のブックマークをドキュメントに挿入し、一意の名前でブックマークを識別することでそれらをナビゲートできます。 ブックマークに移動するには、MoveToBookmarkメソッドを使用します。

次のコード例は、カーソル位置をブックマークに移動する方法を示しています:

For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-C
auto doc = System::MakeObject<Document>();
auto builder = System::MakeObject<DocumentBuilder>(doc);

// Start a bookmark and add content to it using a DocumentBuilder.
builder->StartBookmark(u"MyBookmark");
builder->Writeln(u"Bookmark contents.");
builder->EndBookmark(u"MyBookmark");

// If we wish to revise the content of our bookmark with the DocumentBuilder, we can move back to it like this.
builder->MoveToBookmark(u"MyBookmark");

// Now we're located between the bookmark's BookmarkStart and BookmarkEnd nodes, so any text the builder adds will be within it.
ASSERT_EQ(doc->get_Range()->get_Bookmarks()->idx_get(0)->get_BookmarkStart(), builder->get_CurrentParagraph()->get_FirstChild());

// We can move the builder to an individual node,
// which in this case will be the first node of the first paragraph, like this.
builder->MoveTo(doc->get_FirstSection()->get_Body()->get_FirstParagraph()->GetChildNodes(NodeType::Any, false)->idx_get(0));
ASSERT_EQ(NodeType::BookmarkStart, builder->get_CurrentNode()->get_NodeType());

テーブルセルに移動する

テーブルセルに移動するには、MoveToCellメソッドを使用します。 このメソッドを使用すると、特定のテーブル内の任意のセルにカーソルを移動できます。 さらに、MoveToCellメソッド内のセル内の任意の位置または指定された文字にカーソルを移動するインデックスを指定することもできます。

次のコード例は、カーソル位置を指定したテーブルセルに移動する方法を示しています:

For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-C
auto doc = System::MakeObject<Document>(inputDataDir + u"Tables.docx");
auto builder = System::MakeObject<DocumentBuilder>(doc);

// Move the builder to row 3, cell 4 of the first table.
builder->MoveToCell(0, 2, 3, 0);
builder->Write(u"\nCell contents added by DocumentBuilder");
auto table = System::DynamicCast<Tables::Table>(doc->GetChild(NodeType::Table, 0, true));

ASSERT_EQ(table->get_Rows()->idx_get(2)->get_Cells()->idx_get(3), builder->get_CurrentNode()->get_ParentNode()->get_ParentNode());
ASSERT_EQ(table->get_Rows()->idx_get(2)->get_Cells()->idx_get(2)->GetText().Trim(), u"Cell contents added by DocumentBuilderCell 3 contents\a");

フィールドに移動する

ドキュメント内の特定のフィールドに移動するには、MoveToFieldメソッドを使用します。 また、MoveToMergeFieldメソッドを使用して特定の差し込み項目に移動することもできます。

次のコード例は、document builderカーソルを特定のフィールドに移動する方法を示しています:

For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-C
auto doc = System::MakeObject<Document>();
auto builder = System::MakeObject<DocumentBuilder>(doc);

// Insert a field using the DocumentBuilder and add a run of text after it.
auto field = builder->InsertField(u"MERGEFIELD field");
builder->Write(u" Text after the field.");

// The builder's cursor is currently at end of the document.
ASSERT_EQ(builder->get_CurrentNode(), nullptr);
// We can move the builder to a field like this, placing the cursor at immediately after the field.
builder->MoveToField(field, true);

// Note that the cursor is at a place past the FieldEnd node of the field, meaning that we are not actually inside the field.
// If we wish to move the DocumentBuilder to inside a field,
// we will need to move it to a field's FieldStart or FieldSeparator node using the DocumentBuilder.MoveTo() method.
ASSERT_EQ(field->get_End(), builder->get_CurrentNode()->get_PreviousSibling());
builder->Write(u" Text immediately after the field.");

ヘッダーまたはフッターに移動する

ヘッダーまたはフッターの先頭に移動するには、MoveToHeaderFooterメソッドを使用します。

次のコード例は、ドキュメントビルダーのカーソルをドキュメントヘッダーまたはフッタに移動する方法を示しています:

For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-C
auto doc = System::MakeObject<Document>();
auto builder = System::MakeObject<DocumentBuilder>(doc);

// Specify that we want headers and footers different for first, even and odd pages.
builder->get_PageSetup()->set_DifferentFirstPageHeaderFooter(true);
builder->get_PageSetup()->set_OddAndEvenPagesHeaderFooter(true);

// Create the headers.
builder->MoveToHeaderFooter(HeaderFooterType::HeaderFirst);
builder->Write(u"Header for the first page");
builder->MoveToHeaderFooter(HeaderFooterType::HeaderEven);
builder->Write(u"Header for even pages");
builder->MoveToHeaderFooter(HeaderFooterType::HeaderPrimary);
builder->Write(u"Header for all other pages");

// Create two pages in the document.
builder->MoveToSection(0);
builder->Writeln(u"Page1");
builder->InsertBreak(BreakType::PageBreak);
builder->Writeln(u"Page2");

System::String outputPath = outputDataDir + u"DocumentBuilderMovingCursor.HeadersAndFooters.doc";
doc->Save(outputPath);

セクションまたは段落に移動する

特定のセクションまたは段落に移動するには、MoveToParagraphまたはMoveToSectionメソッドを使用します。 また、MoveToParagraphメソッド内の段落内の任意の位置または指定された文字にカーソルを移動するインデックスを指定することもできます。

次のコード例は、ドキュメント内の特定のセクションと特定の段落に移動する方法を示しています:

For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-C
// Create a blank document and append a section to it, giving it two sections.
auto doc = System::MakeObject<Document>();
doc->AppendChild(System::MakeObject<Section>(doc));

// Move a DocumentBuilder to the second section and add text.
auto builder = System::MakeObject<DocumentBuilder>(doc);
builder->MoveToSection(1);
builder->Writeln(u"Text added to the 2nd section.");

// Create document with paragraphs.
auto doc = System::MakeObject<Document>(inputDataDir + u"Paragraphs.docx");
auto paragraphs = doc->get_FirstSection()->get_Body()->get_Paragraphs();
ASSERT_EQ(paragraphs->get_Count(), 22);

// When we create a DocumentBuilder for a document, its cursor is at the very beginning of the document by default,
// and any content added by the DocumentBuilder will just be prepended to the document.
auto builder = System::MakeObject<DocumentBuilder>(doc);
ASSERT_EQ(paragraphs->IndexOf(builder->get_CurrentParagraph()), 0);

// You can move the cursor to any position in a paragraph.
builder->MoveToParagraph(0, 14);
ASSERT_EQ(paragraphs->IndexOf(builder->get_CurrentParagraph()), 2);
builder->Writeln(u"This is a new third paragraph. ");
ASSERT_EQ(paragraphs->IndexOf(builder->get_CurrentParagraph()), 3);